From ced6e87466308b54caac02ff006c1f1ab9851c6d Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Wed, 21 Aug 2024 12:17:32 +1000 Subject: [PATCH 01/13] Move 'working with the docs site' to a new 'CONTRIBUTING' Markdown page. --- CONTRIBUTING.md | 159 ++++++++++++++++++++++++++ styleguides/markdown-syntax-style.md | 160 --------------------------- 2 files changed, 159 insertions(+), 160 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..df51f4abc8 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,159 @@ +## Working with the docs site + +The Buildkite docs is a custom-built website. This section gives some guidance on working with the setup. + +### Adding and naming new documentation pages + +To add a new documentation page, create it as a *.md file. Give it a lowercase name, separate words using underscores. +To add the new page to the documentation sidebar on https://buildkite.com/docs, add the corresponding entry to +`data/nav.yml` with the following data in the sitetree: + +| Key | Description | Data type | +| ------------- | ----------- | --------- | +| `name` | Menu name | String, required | +| `path` | Enter a relative URL path for internal pages. You can also prepend with `https` for external pages, or `mailto:` for email links. If Path is empty then this will be rendered as a toggle. | String, optional | +| `icon` | Prepend with an icon | String, optional | +| `theme` | WIP: doesn't work yet. Apply a theme. You can use `green` or `purple` | String, optional | +| `children` | Children menu items | Array of objects, optional | +| `pill` | Append a pill. Currently you can use `beta`, `coming-soon`, `deprecated` or `new` | String, optional | +| `new_window` | Make this link open up a new window | Bool, optional | +| `type` | Special nav link types. With `dropdown` the children nav items will be rendered as hover dropdown menus on laptop/desktop screen devices. `link` is a shortcut link that takes the user from one section to another (for example, you may link to SSO under the Integrations section from Pipeline's sidebar). It also renders an 'external link' icon as an affordance. Lastly, `divider` makes a divider line in the nav to help with visual delineation. | String, `dropdown|link|divider`, optional | + +> [!NOTE] +> Ruby, which keeps the website running, interprets underscores in filenames as hyphens. So if a page is called `octopussy_cat.erb.md`, you need to add it as `octopussy-cat` to the `nav.yml` file. + +### Filenames and filename linting + +Use `snake_case` for `*.md` files in `pages`. The [`.ls-lint` linter](https://github.com/buildkite/docs/blob/main/.ls-lint.yml) checks if this rule is observed. +See more about the [ls-lint filename linter](https://ls-lint.org/1.x/getting-started/introduction.html). + +### Escaping vale linting + +If you absolutely need to add some word that triggers the linter, you can use escaping using the following syntax: + +``` + + +This is some text that you do NOT want the linter to check + + +``` + +Use the `vale off` syntax before a phrase that needs to be bypassed by the linter and don't forget to turn it on again with `vale on`. + +### Markdown linting + +A [Markdown linter](https://github.com/DavidAnson/markdownlint) is at work in Buildkite documentation. + +The enabled Markdown linting rules are in [`.markdownlint.yaml`](https://github.com/buildkite/docs/blob/main/.markdownlint.yaml) file. + +### Content reuse (snippets) + +You can use snippets to reuse the same fragment in several documentation pages (single sourcing). This way, you can update the snippet once, and the changes will be visible on all pages that use this snippet. + +Add snippet files to appropriate locations within the `/pages` directory, prefaced with an underscore in the file name. For example `_my_snippet.md`. **However**, when pulling the snippet into a file, remove the leading underscore. + +This way, the following example snippet file located immediately within the `/pages` directory: + +`_step_2_3_github_custom_status.md` + +is referenced using this snippet render link: + +`<%= render_markdown partial: 'step_2_3_github_custom_status' %>` + +Use the snippet render link wherever you need to add the content of the snippet (multiple times if required) in other Markdown files throughout the Buildkite Docs. + +If a snippet is stored within a subdirectory of `/pages`, you need to specify the subdirectory hierarchy in the link to the snippet. + +Therefore, a reference to the `_agent_events_table.md` file stored within the `webhooks` subdirectory of the `apis` subdirectory would look like this: + +`<%= render_markdown partial: 'apis/webhooks/agent_events_table' %>` + +> [!WARNING] +> Do not use H2, H3-level headings in the first line of a snippet because this results in the generation of incorrect anchor links for such headings. Instead, if you need to start a snippet with a heading, add the heading to the main document just before you add a snippet render link. + +### Custom elements + +The Buildkite docs has a few custom scripts for adding useful elements that are missing in Markdown. +To save yourself a few unnecessary rounds of edits in the future, remember that if you see a fragment written in HTML, links within such fragment should also follow the HTML syntax and not Markdown (more on this in [Note blocks](#note-blocks)). + +#### Beta flags + +To mark a content page in the site as being in beta, add its relative path _after_ `docs` to the `app/models/beta_pages.rb` file. + +For example: +``` +[ + 'test-analytics', + 'test-analytics/integrations' +] +``` + +Any file listed there will automatically pick up the beta styling. + +Adding the class `has-pill-beta` to any element will append the beta pill. This is intended for use in the sidebar and homepage navigation and will not work in Markdown. + +#### Table of contents + +Table of contents are automatically generated based on \##\-level headings. + +You can omit a table of contents by adding some additional metadata to a Markdown template using the following YAML front matter: + +```yaml +--- +toc: false +--- +``` + +#### Prepending icons + +You can prepend an icon to boost the visual emphasis for an inline text. To do this, wrap the text with ``. + +At the time of writing, there are only three icons available — agent, repository, and plugin. To add more icons see `$icons` in `_add-icon.scss`, add a new name as the key and the inline SVG. Icon dimension must be 22px * 22px. + +> [!NOTE] +> Unlike emojis, these icons are generic and contextual, and they are used as to help readers to better visually differentiate specific terms from the rest of the text. + +### Updating vendor\emojis + +From time to time, you will start seeing an update to `vendor\emojis` submodule as a default initial file change in every new branch you create. This happens because these new branches will have an older version of the emoji submodule than the main branch. + +**Do not commit the `vendor\emojis` commit!** Instead, run `git submodule update`. This will take care of the emoji commit - until your local emoji submodule version falls behind again. Then you will need to run `git submodule update` for your local Docs repository again. + +If you do accidentally commit the `vendor\emojis` update, use `git reset --soft HEAD~1` to undo your last commit, un-stage the erroneous submodule change, and commit again. + +## Screenshots + +This information was aggregated by going over the existing screenshots in the documentation repo. Feel free to change or expand it. + +### Taking and processing screenshots + +* **Format:** PNG +* **Ratio:** arbitrary, but **strictly even number of pixels** for both height and width. Recommended size `width: 1024px, height: 880px` when you're taking a full-width screen +* **Size:** the largest possible resolution that makes sense. It's preferable that you take the screenshots on a Mac laptop with a Retina screen using Safari. Images should be exported at double (`@2x`) the original screen. Recommended dimension is `width: 2048/2, height: 880/2` to get the best possible view across different screen sizes. +* **No feature flag:** please remember to turn off all experimental features when taking screenshots +* **Border:** no border +* **Drop shadow:** no +* **Cursor:** include when relevant +* **Area highlight selection:** subtract overlay +* **Blur:** use to obscure sensitive info like passwords or real email addresses; even, non-pixelated +* **User info:** blur out everything except for the name +* **Dummy data:** use Acme Inc as dummy company title +* **Naming screenshots:** lowercase, words separated by hyphens; number after the title, for example, "installation-1" + +### Adding screenshots or other images + +> Before you proceed, make sure that both the width and the height of the image are an even number of pixels! + +Steps for adding add an image to a documentation page: +1. Name the image file (lowercase, separate words using hyphens; add a number to the filename, for example, 'installation-1' if you are adding several images to the same page) +2. Put the file into the corresponding `images` folder (a folder with the same name as the page you are adding this image to; create such folder if it doesn't exist yet) +3. Compose relevant alt text for the image file using sentence case +4. Add your image file to the documentation page using the following code example `<%= image "your-image.png", width: 1110, height: 1110, alt: "Screenshot of Important Feature" %>`. +For large images/screenshots taken on a retina screen, use `<%= image "your-image.png", width: 1110/2, height: 1110/2, alt: "Screenshot of Important Feature" %>`. + +## Talking about YAML + +YAML looks more simple than it is. +It takes some care and discipline to write about. +See [Talking about YAML](./yaml.md) for complete guidance. diff --git a/styleguides/markdown-syntax-style.md b/styleguides/markdown-syntax-style.md index 6e20d50e39..ebb9b25e42 100644 --- a/styleguides/markdown-syntax-style.md +++ b/styleguides/markdown-syntax-style.md @@ -432,163 +432,3 @@ steps: Here it is also necessary to use emoji escaping as the documentation website considers custom emojis and expressions surrounded by colons in code snippets to be images and will try to render them into png image links within the code snippets. For example,`:aws:` will be rendered as: `"`. Use escaping to prevent this. - -## Working with the docs site - -The Buildkite docs is a custom-built website. This section gives some guidance on working with the setup. - -### Adding and naming new documentation pages - -To add a new documentation page, create it as a *.md file. Give it a lowercase name, separate words using underscores. -To add the new page to the documentation sidebar on https://buildkite.com/docs, add the corresponding entry to -`data/nav.yml` with the following data in the sitetree: - -| Key | Description | Data type | -| ------------- | ----------- | --------- | -| `name` | Menu name | String, required | -| `path` | Enter a relative URL path for internal pages. You can also prepend with `https` for external pages, or `mailto:` for email links. If Path is empty then this will be rendered as a toggle. | String, optional | -| `icon` | Prepend with an icon | String, optional | -| `theme` | WIP: doesn't work yet. Apply a theme. You can use `green` or `purple` | String, optional | -| `children` | Children menu items | Array of objects, optional | -| `pill` | Append a pill. Currently you can use `beta`, `coming-soon`, `deprecated` or `new` | String, optional | -| `new_window` | Make this link open up a new window | Bool, optional | -| `type` | Special nav link types. With `dropdown` the children nav items will be rendered as hover dropdown menus on laptop/desktop screen devices. `link` is a shortcut link that takes the user from one section to another (for example, you may link to SSO under the Integrations section from Pipeline's sidebar). It also renders an 'external link' icon as an affordance. Lastly, `divider` makes a divider line in the nav to help with visual delineation. | String, `dropdown|link|divider`, optional | - -> [!NOTE] -> Ruby, which keeps the website running, interprets underscores in filenames as hyphens. So if a page is called `octopussy_cat.erb.md`, you need to add it as `octopussy-cat` to the `nav.yml` file. - -### Filenames and filename linting - -Use `snake_case` for `*.md` files in `pages`. The [`.ls-lint` linter](https://github.com/buildkite/docs/blob/main/.ls-lint.yml) checks if this rule is observed. -See more about the [ls-lint filename linter](https://ls-lint.org/1.x/getting-started/introduction.html). - -### Escaping vale linting - -If you absolutely need to add some word that triggers the linter, you can use escaping using the following syntax: - -``` - - -This is some text that you do NOT want the linter to check - - -``` - -Use the `vale off` syntax before a phrase that needs to be bypassed by the linter and don't forget to turn it on again with `vale on`. - -### Markdown linting - -A [Markdown linter](https://github.com/DavidAnson/markdownlint) is at work in Buildkite documentation. - -The enabled Markdown linting rules are in [`.markdownlint.yaml`](https://github.com/buildkite/docs/blob/main/.markdownlint.yaml) file. - -### Content reuse (snippets) - -You can use snippets to reuse the same fragment in several documentation pages (single sourcing). This way, you can update the snippet once, and the changes will be visible on all pages that use this snippet. - -Add snippet files to appropriate locations within the `/pages` directory, prefaced with an underscore in the file name. For example `_my_snippet.md`. **However**, when pulling the snippet into a file, remove the leading underscore. - -This way, the following example snippet file located immediately within the `/pages` directory: - -`_step_2_3_github_custom_status.md` - -is referenced using this snippet render link: - -`<%= render_markdown partial: 'step_2_3_github_custom_status' %>` - -Use the snippet render link wherever you need to add the content of the snippet (multiple times if required) in other Markdown files throughout the Buildkite Docs. - -If a snippet is stored within a subdirectory of `/pages`, you need to specify the subdirectory hierarchy in the link to the snippet. - -Therefore, a reference to the `_agent_events_table.md` file stored within the `webhooks` subdirectory of the `apis` subdirectory would look like this: - -`<%= render_markdown partial: 'apis/webhooks/agent_events_table' %>` - -> [!WARNING] -> Do not use H2, H3-level headings in the first line of a snippet because this results in the generation of incorrect anchor links for such headings. Instead, if you need to start a snippet with a heading, add the heading to the main document just before you add a snippet render link. - -### Custom elements - -The Buildkite docs has a few custom scripts for adding useful elements that are missing in Markdown. -To save yourself a few unnecessary rounds of edits in the future, remember that if you see a fragment written in HTML, links within such fragment should also follow the HTML syntax and not Markdown (more on this in [Note blocks](#note-blocks)). - -#### Beta flags - -To mark a content page in the site as being in beta, add its relative path _after_ `docs` to the `app/models/beta_pages.rb` file. - -For example: -``` -[ - 'test-analytics', - 'test-analytics/integrations' -] -``` - -Any file listed there will automatically pick up the beta styling. - -Adding the class `has-pill-beta` to any element will append the beta pill. This is intended for use in the sidebar and homepage navigation and will not work in Markdown. - -#### Table of contents - -Table of contents are automatically generated based on \##\-level headings. - -You can omit a table of contents by adding some additional metadata to a Markdown template using the following YAML front matter: - -```yaml ---- -toc: false ---- -``` - -#### Prepending icons - -You can prepend an icon to boost the visual emphasis for an inline text. To do this, wrap the text with ``. - -At the time of writing, there are only three icons available — agent, repository, and plugin. To add more icons see `$icons` in `_add-icon.scss`, add a new name as the key and the inline SVG. Icon dimension must be 22px * 22px. - -> [!NOTE] -> Unlike emojis, these icons are generic and contextual, and they are used as to help readers to better visually differentiate specific terms from the rest of the text. - -### Updating vendor\emojis - -From time to time, you will start seeing an update to `vendor\emojis` submodule as a default initial file change in every new branch you create. This happens because these new branches will have an older version of the emoji submodule than the main branch. - -**Do not commit the `vendor\emojis` commit!** Instead, run `git submodule update`. This will take care of the emoji commit - until your local emoji submodule version falls behind again. Then you will need to run `git submodule update` for your local Docs repository again. - -If you do accidentally commit the `vendor\emojis` update, use `git reset --soft HEAD~1` to undo your last commit, un-stage the erroneous submodule change, and commit again. - -## Screenshots - -This information was aggregated by going over the existing screenshots in the documentation repo. Feel free to change or expand it. - -### Taking and processing screenshots - -* **Format:** PNG -* **Ratio:** arbitrary, but **strictly even number of pixels** for both height and width. Recommended size `width: 1024px, height: 880px` when you're taking a full-width screen -* **Size:** the largest possible resolution that makes sense. It's preferable that you take the screenshots on a Mac laptop with a Retina screen using Safari. Images should be exported at double (`@2x`) the original screen. Recommended dimension is `width: 2048/2, height: 880/2` to get the best possible view across different screen sizes. -* **No feature flag:** please remember to turn off all experimental features when taking screenshots -* **Border:** no border -* **Drop shadow:** no -* **Cursor:** include when relevant -* **Area highlight selection:** subtract overlay -* **Blur:** use to obscure sensitive info like passwords or real email addresses; even, non-pixelated -* **User info:** blur out everything except for the name -* **Dummy data:** use Acme Inc as dummy company title -* **Naming screenshots:** lowercase, words separated by hyphens; number after the title, for example, "installation-1" - -### Adding screenshots or other images - -> Before you proceed, make sure that both the width and the height of the image are an even number of pixels! - -Steps for adding add an image to a documentation page: -1. Name the image file (lowercase, separate words using hyphens; add a number to the filename, for example, 'installation-1' if you are adding several images to the same page) -2. Put the file into the corresponding `images` folder (a folder with the same name as the page you are adding this image to; create such folder if it doesn't exist yet) -3. Compose relevant alt text for the image file using sentence case -4. Add your image file to the documentation page using the following code example `<%= image "your-image.png", width: 1110, height: 1110, alt: "Screenshot of Important Feature" %>`. -For large images/screenshots taken on a retina screen, use `<%= image "your-image.png", width: 1110/2, height: 1110/2, alt: "Screenshot of Important Feature" %>`. - -## Talking about YAML - -YAML looks more simple than it is. -It takes some care and discipline to write about. -See [Talking about YAML](./yaml.md) for complete guidance. From 5e02abafcf8b277ce6ad8827a6d1dfc68b225028 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Wed, 21 Aug 2024 13:50:34 +1000 Subject: [PATCH 02/13] Add introductory material to CONTRIBUTING page. --- CONTRIBUTING.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index df51f4abc8..c4785bd11c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,12 @@ +# Contributing to the Buildkite Docs + +This guide provides details on how to work with the Buildkite Docs source code, which generates the [Buildkite Docs](https://buildkite.com/docs/) web site. + +Please also note the following style guides, which are relevant to adding content to pages within this site: + +- [Writing style guide](./styleguides/writing-style.md) +- [Markdown syntax style guide](./styleguides/markdown-syntax-style.md) + ## Working with the docs site The Buildkite docs is a custom-built website. This section gives some guidance on working with the setup. From 242349b32fddf68402a019eb0f5f7c319ca297a9 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Wed, 21 Aug 2024 14:25:42 +1000 Subject: [PATCH 03/13] Incorporate public CONTRIBUTING guide to README. --- README.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index c43cdfb2bd..10af413a52 100644 --- a/README.md +++ b/README.md @@ -104,17 +104,21 @@ bundle exec rake graphql:generate ## Linting -We spell-check the docs (US English) and run a few automated checks for repeated words, common errors, and markdown and filename inconsistencies. +The docs (US English) are spell-checked and a few automated checks for repeated words, common errors, and markdown and filename inconsistencies are also run. You can run most of these checks with `./scripts/vale.sh`. If you've added a new valid word that showing up as a spelling error, add it to `./vale/styles/vocab.txt`. -## Style guides +## Contributing and style guides -Our documentation is based on the principles of common sense, clarity, and brevity. +The Buildkite Docs is based on the principles of common sense, clarity, and brevity. -The [writing](/styleguides/writing-style.md) and [Markdown syntax](/styleguides/markdown-syntax-style.md) style guides should provide you a general idea and an insight into our language and writing style, as well as the Markdown syntax we use (including custom formatting elements). +Refer to the: + +- [Contributing to the Buildkite Docs](CONTRIBUTING.md) guide for details on how to start making a contribution in a new pull request. + +- [writing](/styleguides/writing-style.md) and [Markdown syntax](/styleguides/markdown-syntax-style.md) style guides, which should provide a general idea and an insight into the language and writing style used throughout the Buildkite Docs, as well as the Markdown syntax used (including custom formatting elements). ## Search index @@ -149,9 +153,9 @@ Otherwise, to update the general navigation: ## Content keywords -We render content keywords in `data-content-keywords` in the `body` tag to highlight the focus keywords of each page with content authors. +Content keywords are rendered in `data-content-keywords` in the `body` tag to highlight the focus keywords of each page with content authors. -This helps the content team to quickly inspect to see the types of content we're providing across different channels. +This helps the main documentation contribution team quickly inspect to see the types of content Buildkite provides across different channels. Keywords are added as [Frontmatter](https://rubygems.org/gems/front_matter_parser) meta data using the `keywords` key, e.g.: From 5af071fb2afd5c56f96228c3d455d8228fe1d76f Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Wed, 21 Aug 2024 14:27:11 +1000 Subject: [PATCH 04/13] Minor improvements. --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c4785bd11c..dcbb3f4c8d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -123,13 +123,13 @@ At the time of writing, there are only three icons available — agent, reposito > [!NOTE] > Unlike emojis, these icons are generic and contextual, and they are used as to help readers to better visually differentiate specific terms from the rest of the text. -### Updating vendor\emojis +### Updating vendor/emojis -From time to time, you will start seeing an update to `vendor\emojis` submodule as a default initial file change in every new branch you create. This happens because these new branches will have an older version of the emoji submodule than the main branch. +From time to time, you will start seeing an update to `vendor/emojis` submodule as a default initial file change in every new branch you create. This happens because these new branches will have an older version of the emoji submodule than the main branch. -**Do not commit the `vendor\emojis` commit!** Instead, run `git submodule update`. This will take care of the emoji commit - until your local emoji submodule version falls behind again. Then you will need to run `git submodule update` for your local Docs repository again. +**Do not commit the `vendor/emojis` commit!** Instead, run `git submodule update`. This will take care of the emoji commit - until your local emoji submodule version falls behind again. Then you will need to run `git submodule update` for your local Docs repository again. -If you do accidentally commit the `vendor\emojis` update, use `git reset --soft HEAD~1` to undo your last commit, un-stage the erroneous submodule change, and commit again. +If you do accidentally commit the `vendor/emojis` update, use `git reset --soft HEAD~1` to undo your last commit, un-stage the erroneous submodule change, and commit again. ## Screenshots From ff576f89b6082975ba66bfe271e21a19f04a0c96 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Wed, 21 Aug 2024 14:37:50 +1000 Subject: [PATCH 05/13] Amend screenshot guidelines. --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dcbb3f4c8d..99f523312c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -139,7 +139,7 @@ This information was aggregated by going over the existing screenshots in the do * **Format:** PNG * **Ratio:** arbitrary, but **strictly even number of pixels** for both height and width. Recommended size `width: 1024px, height: 880px` when you're taking a full-width screen -* **Size:** the largest possible resolution that makes sense. It's preferable that you take the screenshots on a Mac laptop with a Retina screen using Safari. Images should be exported at double (`@2x`) the original screen. Recommended dimension is `width: 2048/2, height: 880/2` to get the best possible view across different screen sizes. +* **Size:** the largest possible resolution that makes sense. It's preferable that you take the screenshots on a Mac laptop with a Retina or high-resolution display/screen. Recommended dimension is `width: 2048/2, height: 880/2` to get the best possible view across different screen sizes. * **No feature flag:** please remember to turn off all experimental features when taking screenshots * **Border:** no border * **Drop shadow:** no From 5e4d12686868dffc166185790d07802adb45996d Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Wed, 21 Aug 2024 15:38:15 +1000 Subject: [PATCH 06/13] Add a little more context to the contributor's guide. --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 99f523312c..8403ff088d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to the Buildkite Docs -This guide provides details on how to work with the Buildkite Docs source code, which generates the [Buildkite Docs](https://buildkite.com/docs/) web site. +This guide provides details on how to work with the Buildkite Docs source code, which generates the [Buildkite Docs](https://buildkite.com/docs/) web site, and make contributions to its content. Please also note the following style guides, which are relevant to adding content to pages within this site: From d481f02f92e29f1e03f745a778794e47d97d4774 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Tue, 27 Aug 2024 13:51:24 +1000 Subject: [PATCH 07/13] Update CODEOWNERS file. --- CODEOWNERS | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/CODEOWNERS b/CODEOWNERS index fdaa376ab4..d65eecf529 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -1,10 +1,7 @@ @dannymidnight -pages/ @mbelton-buildkite @gilesgas -data/ @mbelton-buildkite @gilesgas -images/ @mbelton-buildkite @gilesgas -vale/ @mbelton-buildkite @gilesgas -styleguide/ @mbelton-buildkite @gilesgas - -app/assets/ @buildkite/growth-activate -app/views/ @buildkite/growth-activate +pages/ @gilesgas +data/ @gilesgas +images/ @gilesgas +vale/ @gilesgas +styleguide/ @gilesgas From d2376d08ac0a1dd6a82e614e43efc6af478a03ad Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Wed, 28 Aug 2024 11:42:57 +1000 Subject: [PATCH 08/13] Rework intro to CONTRIBUTING guide. --- CONTRIBUTING.md | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8403ff088d..9e1d9bc25b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,25 +11,31 @@ Please also note the following style guides, which are relevant to adding conten The Buildkite docs is a custom-built website. This section gives some guidance on working with the setup. -### Adding and naming new documentation pages +### Add a new docs page and nav entry -To add a new documentation page, create it as a *.md file. Give it a lowercase name, separate words using underscores. -To add the new page to the documentation sidebar on https://buildkite.com/docs, add the corresponding entry to -`data/nav.yml` with the following data in the sitetree: +To add a new documentation (docs) page and a nav entry for it: + +1. Create the file as a new Markdown file (with the extension `.md`) within the appropriate `pages` directory. Ensure the file name is written in all lowercase letters, and separate words using underscores. (These underscores will be automatically converted to hyphens when the Buildkite Docs site is rebuilt.) + +1. Add a corresponding entry to this new page in the `data/nav.yml` file, which adds a new entry for this page in the page navigation sidebar (nav) of the [Buildkite Docs site](https://buildkite.com/docs). Note the existing page entries in `nav.yml` and use them as a guide to determine the location and hence, placement of the entry to your new Markdown file (in the nav and `nav.yml`). The following elements require considering for a new entry in `nav.yml`: | Key | Description | Data type | | ------------- | ----------- | --------- | -| `name` | Menu name | String, required | -| `path` | Enter a relative URL path for internal pages. You can also prepend with `https` for external pages, or `mailto:` for email links. If Path is empty then this will be rendered as a toggle. | String, optional | -| `icon` | Prepend with an icon | String, optional | -| `theme` | WIP: doesn't work yet. Apply a theme. You can use `green` or `purple` | String, optional | -| `children` | Children menu items | Array of objects, optional | +| `name` | Nav entry name (see note below). | String, required | +| `path` | Enter a relative URL path for internal pages. You can also prepend with `https` for external pages, or `mailto:` for email links, although this practice should be avoided or minimized. If the `path` is empty or omitted, then this will be rendered as a toggle that opens a new section of pages. | String, optional | +| `icon` | Prepend with an icon. | String, optional | +| `theme` | WIP: doesn't work yet. Apply a theme. You can use `green` or `purple`. | String, optional | +| `children` | Child nav entry items. | Array of objects, optional | | `pill` | Append a pill. Currently you can use `beta`, `coming-soon`, `deprecated` or `new` | String, optional | -| `new_window` | Make this link open up a new window | Bool, optional | +| `new_window` | Make this link open up a new window, although this practice should be avoided or minimized. | Bool, optional | | `type` | Special nav link types. With `dropdown` the children nav items will be rendered as hover dropdown menus on laptop/desktop screen devices. `link` is a shortcut link that takes the user from one section to another (for example, you may link to SSO under the Integrations section from Pipeline's sidebar). It also renders an 'external link' icon as an affordance. Lastly, `divider` makes a divider line in the nav to help with visual delineation. | String, `dropdown|link|divider`, optional | > [!NOTE] -> Ruby, which keeps the website running, interprets underscores in filenames as hyphens. So if a page is called `octopussy_cat.erb.md`, you need to add it as `octopussy-cat` to the `nav.yml` file. +> The Buildkite Docs web site is kept running with Ruby, which interprets underscores in filenames as hyphens. Therefore, if a page is called `octopussy_cat.md`, then for its entry in the `nav.yml` file, you need to reference its `path` key value as `octopussy-cat`. +> +> If you're creating a new section for the nav, then as described for the `path` key above, add the `name` entry, omit its `path` key, add a `children` key for this entry, and then nest/indent all new page entries within this section entry. +> +> Since a new section entry in the nav cannot hold a page, then to introduce this page, create an "Overview" page for this section. ### Filenames and filename linting From 74c810102c2070570b4e2300ef81238f8e0d44f0 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Wed, 28 Aug 2024 11:52:04 +1000 Subject: [PATCH 09/13] A few wording tweaks. --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9e1d9bc25b..0134c2f990 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,9 +33,9 @@ To add a new documentation (docs) page and a nav entry for it: > [!NOTE] > The Buildkite Docs web site is kept running with Ruby, which interprets underscores in filenames as hyphens. Therefore, if a page is called `octopussy_cat.md`, then for its entry in the `nav.yml` file, you need to reference its `path` key value as `octopussy-cat`. > -> If you're creating a new section for the nav, then as described for the `path` key above, add the `name` entry, omit its `path` key, add a `children` key for this entry, and then nest/indent all new page entries within this section entry. +> If you're creating a new section for the nav, then as described for the `path` key above, add the `name` key for this entry, omit its `path` key, and add a `children` key to create this new section. Then, nest/indent all new page entries within this section entry. > -> Since a new section entry in the nav cannot hold a page, then to introduce this page, create an "Overview" page for this section. +> Since a new section entry in the nav is purely a toggle that cannot hold page content itself, then to introduce a page for this new section, create a top-level "Overview" page for this section instead. ### Filenames and filename linting From 7076b8f99a4840150f7ce0c1059f74a9c07fe1b8 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Wed, 28 Aug 2024 17:43:04 +1000 Subject: [PATCH 10/13] Refactored linting section of the public contributors guide. --- CONTRIBUTING.md | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0134c2f990..abc13d0911 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,14 +37,26 @@ To add a new documentation (docs) page and a nav entry for it: > > Since a new section entry in the nav is purely a toggle that cannot hold page content itself, then to introduce a page for this new section, create a top-level "Overview" page for this section instead. -### Filenames and filename linting +### Linting -Use `snake_case` for `*.md` files in `pages`. The [`.ls-lint` linter](https://github.com/buildkite/docs/blob/main/.ls-lint.yml) checks if this rule is observed. -See more about the [ls-lint filename linter](https://ls-lint.org/1.x/getting-started/introduction.html). +This section describes the various linting features which are run as part of the Buildkite Docs build pipeline. -### Escaping vale linting +#### Markdown files -If you absolutely need to add some word that triggers the linter, you can use escaping using the following syntax: +Markdown files must be located within `pages`, and their names must be written in [`snake_case`](https://simple.wikipedia.org/wiki/Snake_case) and end with the `.md` extension. + +The [`.ls-lint` linter](https://github.com/buildkite/docs/blob/main/.ls-lint.yml) checks if this rule is observed. +Learn more about the [ls-lint filename linter](https://ls-lint.org/1.x/getting-started/introduction.html). + +#### Markdown content + +A [Markdown linter](https://github.com/DavidAnson/markdownlint) also runs on the Buildkite documentation's Markdown file content. + +The rules enabled for this Markdown linting are defined in the [`.markdownlint.yaml`](https://github.com/buildkite/docs/blob/main/.markdownlint.yaml) file. + +#### Escaping vale linting + +If you absolutely need to add some word or syntax that would trigger the linter into failing the docs build pipeline, you can use escaping using the following syntax: ``` @@ -56,12 +68,6 @@ This is some text that you do NOT want the linter to check Use the `vale off` syntax before a phrase that needs to be bypassed by the linter and don't forget to turn it on again with `vale on`. -### Markdown linting - -A [Markdown linter](https://github.com/DavidAnson/markdownlint) is at work in Buildkite documentation. - -The enabled Markdown linting rules are in [`.markdownlint.yaml`](https://github.com/buildkite/docs/blob/main/.markdownlint.yaml) file. - ### Content reuse (snippets) You can use snippets to reuse the same fragment in several documentation pages (single sourcing). This way, you can update the snippet once, and the changes will be visible on all pages that use this snippet. From 9d80a8561cd50d324d19883a1145c72c8c96bdd6 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Wed, 28 Aug 2024 18:03:07 +1000 Subject: [PATCH 11/13] Add section on fixing spelling errors. --- CONTRIBUTING.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index abc13d0911..721c841907 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,7 +17,7 @@ To add a new documentation (docs) page and a nav entry for it: 1. Create the file as a new Markdown file (with the extension `.md`) within the appropriate `pages` directory. Ensure the file name is written in all lowercase letters, and separate words using underscores. (These underscores will be automatically converted to hyphens when the Buildkite Docs site is rebuilt.) -1. Add a corresponding entry to this new page in the `data/nav.yml` file, which adds a new entry for this page in the page navigation sidebar (nav) of the [Buildkite Docs site](https://buildkite.com/docs). Note the existing page entries in `nav.yml` and use them as a guide to determine the location and hence, placement of the entry to your new Markdown file (in the nav and `nav.yml`). The following elements require considering for a new entry in `nav.yml`: +1. Add a corresponding entry to this new page in the [`data/nav.yml`](./data/nav.yml) file, which adds a new entry for this page in the page navigation sidebar (nav) of the [Buildkite Docs site](https://buildkite.com/docs). Note the existing page entries in `nav.yml` and use them as a guide to determine the location and hence, placement of the entry to your new Markdown file (in the nav and `nav.yml`). The following elements require considering for a new entry in `nav.yml`: | Key | Description | Data type | | ------------- | ----------- | --------- | @@ -45,14 +45,22 @@ This section describes the various linting features which are run as part of the Markdown files must be located within `pages`, and their names must be written in [`snake_case`](https://simple.wikipedia.org/wiki/Snake_case) and end with the `.md` extension. -The [`.ls-lint` linter](https://github.com/buildkite/docs/blob/main/.ls-lint.yml) checks if this rule is observed. +The [`.ls-lint.yml`](.ls-lint.yml) linter file contains rules that the ls-lint filename linter checks are observed. Learn more about the [ls-lint filename linter](https://ls-lint.org/1.x/getting-started/introduction.html). #### Markdown content A [Markdown linter](https://github.com/DavidAnson/markdownlint) also runs on the Buildkite documentation's Markdown file content. -The rules enabled for this Markdown linting are defined in the [`.markdownlint.yaml`](https://github.com/buildkite/docs/blob/main/.markdownlint.yaml) file. +The rules enabled for this Markdown linting are defined in the [`.markdownlint.yaml`](.markdownlint.yaml) file. + +#### Fixing spelling errors + +The Buildkite Docs build pipeline uses [Vale](https://vale.sh/) to check for spelling errors, and builds will fail if a spelling error is encountered. + +If you need to add an exception to this (for example, you are referencing a new technology or tool that isn't in Vale's vocabulary), add this term verbatim to the [`/vale/styles/vocab.txt`](./vale/styles/vocab.txt) file, ensuring that the term is added in the correct alphabetical order within the file. Case is important but should be ignored with regard to alphabetical ordering within the file. This makes it easier to identify if an exception has already been added. + +If you encounter a spelling error within a heading, add this entry into the [`/vale/styles/Buildkite/h1-h6_sentence_case.yml`](./vale/styles/Buildkite/h1-h6_sentence_case.yml) file. #### Escaping vale linting From 2e9a277b7e85a42cbcfa823322c936e15c724d46 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Thu, 29 Aug 2024 11:48:25 +1000 Subject: [PATCH 12/13] Moved contribution content from README to CONTRIBUTING --- CONTRIBUTING.md | 82 ++++++++++++++++++++++++++++++++++++++++++---- README.md | 87 +++---------------------------------------------- 2 files changed, 79 insertions(+), 90 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 721c841907..7a47f1daad 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,6 +31,8 @@ To add a new documentation (docs) page and a nav entry for it: | `type` | Special nav link types. With `dropdown` the children nav items will be rendered as hover dropdown menus on laptop/desktop screen devices. `link` is a shortcut link that takes the user from one section to another (for example, you may link to SSO under the Integrations section from Pipeline's sidebar). It also renders an 'external link' icon as an affordance. Lastly, `divider` makes a divider line in the nav to help with visual delineation. | String, `dropdown|link|divider`, optional | > [!NOTE] +> Whenever you save changes to the `nav.yml` file, you'll need to stop and restart your local development environment in order to see these changes reflected in the nav. +> > The Buildkite Docs web site is kept running with Ruby, which interprets underscores in filenames as hyphens. Therefore, if a page is called `octopussy_cat.md`, then for its entry in the `nav.yml` file, you need to reference its `path` key value as `octopussy-cat`. > > If you're creating a new section for the nav, then as described for the `path` key above, add the `name` key for this entry, omit its `path` key, and add a `children` key to create this new section. Then, nest/indent all new page entries within this section entry. @@ -41,6 +43,10 @@ To add a new documentation (docs) page and a nav entry for it: This section describes the various linting features which are run as part of the Buildkite Docs build pipeline. +The docs (in US English) are spell-checked and a few automated checks for repeated words, common errors, and Markdown and filename inconsistencies are also run. + +You can run most of these checks locally with [`./scripts/vale.sh`](./scripts/vale.sh). + #### Markdown files Markdown files must be located within `pages`, and their names must be written in [`snake_case`](https://simple.wikipedia.org/wiki/Snake_case) and end with the `.md` extension. @@ -54,7 +60,7 @@ A [Markdown linter](https://github.com/DavidAnson/markdownlint) also runs on the The rules enabled for this Markdown linting are defined in the [`.markdownlint.yaml`](.markdownlint.yaml) file. -#### Fixing spelling errors +#### Fix spelling errors The Buildkite Docs build pipeline uses [Vale](https://vale.sh/) to check for spelling errors, and builds will fail if a spelling error is encountered. @@ -62,7 +68,7 @@ If you need to add an exception to this (for example, you are referencing a new If you encounter a spelling error within a heading, add this entry into the [`/vale/styles/Buildkite/h1-h6_sentence_case.yml`](./vale/styles/Buildkite/h1-h6_sentence_case.yml) file. -#### Escaping vale linting +#### Escape vale linting If you absolutely need to add some word or syntax that would trigger the linter into failing the docs build pipeline, you can use escaping using the following syntax: @@ -76,9 +82,9 @@ This is some text that you do NOT want the linter to check Use the `vale off` syntax before a phrase that needs to be bypassed by the linter and don't forget to turn it on again with `vale on`. -### Content reuse (snippets) +### Content reuse (snippets/partials) -You can use snippets to reuse the same fragment in several documentation pages (single sourcing). This way, you can update the snippet once, and the changes will be visible on all pages that use this snippet. +You can use snippets or partials to reuse the same fragment in several documentation pages (single sourcing). This way, you can update the snippet once, and the changes will be visible on all pages that use this snippet. Add snippet files to appropriate locations within the `/pages` directory, prefaced with an underscore in the file name. For example `_my_snippet.md`. **However**, when pulling the snippet into a file, remove the leading underscore. @@ -124,7 +130,7 @@ Adding the class `has-pill-beta` to any element will append the beta pill. This #### Table of contents -Table of contents are automatically generated based on \##\-level headings. +Table of contents are automatically generated based on `##`-level headings. You can omit a table of contents by adding some additional metadata to a Markdown template using the following YAML front matter: @@ -134,7 +140,7 @@ toc: false --- ``` -#### Prepending icons +#### Prepend icons You can prepend an icon to boost the visual emphasis for an inline text. To do this, wrap the text with ``. @@ -143,7 +149,38 @@ At the time of writing, there are only three icons available — agent, reposito > [!NOTE] > Unlike emojis, these icons are generic and contextual, and they are used as to help readers to better visually differentiate specific terms from the rest of the text. -### Updating vendor/emojis +### Update Buildkite Agent CLI docs + +The [Buildkite Agent command-line interface (CLI) reference docs](https://buildkite.com/docs/agent/v3/cli-reference) consists of a series of pages where each page describes how each of the agent's `buildkite-agent` CLI commands works and is used. + +Each command's docs page should have a **Usage**, **Description**, **Example**, and **Options** section appearing somewhere on the page. + +These four sections are actually part of a [partial](#content-reuse-snippetspartials), whose content comes from its relevant Markdown file partial in the [docs source repo's `pages/agent/v3/help` folder](./pages/agent/v3/help). The files in this folder are automatically updated whenever a [new version of the Buildkite Agent is released](https://github.com/buildkite/agent/releases), containing updates to the documentation in any of its relevant [clicommand files](https://github.com/buildkite/agent/tree/main/clicommand). This is why the tops of these file partials indicate **DO NOT EDIT**. + +With the development dependencies installed you can update these CLI docs locally with the following: + +```bash +# Set a custom PATH to select a locally built buildkite-agent +PATH="$HOME/Projects/buildkite/agent:$PATH" ./scripts/update-agent-help.sh +``` + +### Update the GraphQL API docs + +The GraphQL API reference documentation (from the start of [Queries](https://buildkite.com/docs/apis/graphql/schemas/query/agent) through to end of [Unions](https://buildkite.com/docs/apis/graphql/schemas/union/usageunion)) is generated from a local version of the [Buildkite GraphQL API schema](./data/graphql/schema.graphql). + +This repository is kept up-to-date with production based on a daily scheduled build that generates a pull request. The build fetches the latest GraphQL schema from the Buildkite API, generates the documentation, and publishes a pull request for review. + +If you need to fetch the latest schema, you can run the following in your local environment: + +```sh +# Fetch latest schema +API_ACCESS_TOKEN=xxx bundle exec rake graphql:fetch_schema >| data/graphql/schema.graphql + +# Generate docs based on latest schema +bundle exec rake graphql:generate +``` + +### Update vendor/emojis From time to time, you will start seeing an update to `vendor/emojis` submodule as a default initial file change in every new branch you create. This happens because these new branches will have an older version of the emoji submodule than the main branch. @@ -151,6 +188,37 @@ From time to time, you will start seeing an update to `vendor/emojis` submodule If you do accidentally commit the `vendor/emojis` update, use `git reset --soft HEAD~1` to undo your last commit, un-stage the erroneous submodule change, and commit again. +### Search index + +**Note:** By default, search (through Algolia) references the production search index. + +The search index is updated once a day by a scheduled build using the config in `config/algolia.json`. + +To test changes to the indexing configuration: + +1. Make sure you have an API key in `.env` like: + + ```env + APPLICATION_ID=APP_ID + API_KEY=YOUR_API_KEY + ``` + +2. Run `bundle exec rake update_test_index`. + +### Content keywords + +Content keywords are rendered in `data-content-keywords` in the `body` tag to highlight the focus keywords of each page with content authors. + +This helps the main documentation contribution team quickly inspect to see the types of content Buildkite provides across different channels. + +Keywords are added as [Frontmatter](https://rubygems.org/gems/front_matter_parser) meta data using the `keywords` key, e.g.: + +```md +keywords: docs, tutorial, pipelines, 2fa +``` + +If no keywords are provided it falls back to comma-separated URL path segments. + ## Screenshots This information was aggregated by going over the existing screenshots in the documentation repo. Feel free to change or expand it. diff --git a/README.md b/README.md index 10af413a52..8318427a6b 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # Buildkite Documentation [![Build status](https://badge.buildkite.com/b1b9e3ef9d893c087f5e5c0a2d04c258ba393bed2379273f63.svg?branch=main)](https://buildkite.com/buildkite/docs) -The source files for the [Buildkite Documentation](https://buildkite.com/docs). +The source files for the [Buildkite Documentation](https://buildkite.com/docs), aka the Buildkite Docs, or just docs. To contribute, please send a pull request! :heart: -## Development +## Local docs development environment ### Before you start @@ -74,43 +74,9 @@ After completing the relevant 'Before you start' steps above: > [!NOTE] > If you ever make more significant changes than just page updates (for example, adding a new page), you may need to stop and restart the Buildkite Docs development server to see these changes. -## Updating `buildkite-agent` CLI docs +Learn how to contribute to the Buildkite Docs in the [CONTRIBUTING guide](./CONTRIBUTING.md). -With the development dependencies installed you can update the CLI docs with the following: - -```bash -# Set a custom PATH to select a locally built buildkite-agent -PATH="$HOME/Projects/buildkite/agent:$PATH" ./scripts/update-agent-help.sh -``` - -## Updating GraphQL API docs - -GraphQL API documentation is generated from a local version of the [Buildkite GraphQL API schema](./data/graphql/schema.graphql). - -This repository is kept up-to-date with production based on a [daily scheduled build](https://buildkite.com/buildkite/docs-graphql). The build fetches the latest GraphQL schema, generates the documentation, and publishes a pull request for review. - -If you need to fetch the latest schema you can either: - -- Manually trigger a build on [`buildkite/docs-graphql`](https://buildkite.com/buildkite/docs-graphql); or -- Run the following in your local environment: - -```sh -# Fetch latest schema -API_ACCESS_TOKEN=xxx bundle exec rake graphql:fetch_schema >| data/graphql/schema.graphql - -# Generate docs based on latest schema -bundle exec rake graphql:generate -``` - -## Linting - -The docs (US English) are spell-checked and a few automated checks for repeated words, common errors, and markdown and filename inconsistencies are also run. - -You can run most of these checks with `./scripts/vale.sh`. - -If you've added a new valid word that showing up as a spelling error, add it to `./vale/styles/vocab.txt`. - -## Contributing and style guides +## Contributing to the docs and style guides The Buildkite Docs is based on the principles of common sense, clarity, and brevity. @@ -120,51 +86,6 @@ Refer to the: - [writing](/styleguides/writing-style.md) and [Markdown syntax](/styleguides/markdown-syntax-style.md) style guides, which should provide a general idea and an insight into the language and writing style used throughout the Buildkite Docs, as well as the Markdown syntax used (including custom formatting elements). -## Search index - -**Note:** By default, search (through Algolia) references the production search index. - -The search index is updated once a day by a scheduled build using the config in `config/algolia.json`. - -To test changes to the indexing configuration: - -1. Make sure you have an API key in `.env` like: - - ```env - APPLICATION_ID=APP_ID - API_KEY=YOUR_API_KEY - ``` - -2. Run `bundle exec rake update_test_index`. - -## Updating the navigation - -The navigation is split into the following files: - -- `nav_graphql.yml`: For the GraphQL API content. -- `nav.yml`: For everything else. - -A combined navigation is generated when the application starts. - -Otherwise, to update the general navigation: - -1. Edit `nav.yml` with your changes. -1. Restart the application. - -## Content keywords - -Content keywords are rendered in `data-content-keywords` in the `body` tag to highlight the focus keywords of each page with content authors. - -This helps the main documentation contribution team quickly inspect to see the types of content Buildkite provides across different channels. - -Keywords are added as [Frontmatter](https://rubygems.org/gems/front_matter_parser) meta data using the `keywords` key, e.g.: - -```md -keywords: docs, tutorial, pipelines, 2fa -``` - -If no keywords are provided it falls back to comma-separated URL path segments. - ## License See [LICENSE.md](LICENSE.md) (MIT) From 0ba0ceaf37a365c45f55282aa122a33d1d1d51a2 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Thu, 29 Aug 2024 11:54:17 +1000 Subject: [PATCH 13/13] Last few tweaks. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 8318427a6b..67dd616b93 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ git submodule update --init ### Run the development server -After completing the relevant 'Before you start' steps above: +After completing all the relevant [Before you start](#before-you-start) steps above: 1. Build and run your local Buildkite Docs development server environment. @@ -84,7 +84,7 @@ Refer to the: - [Contributing to the Buildkite Docs](CONTRIBUTING.md) guide for details on how to start making a contribution in a new pull request. -- [writing](/styleguides/writing-style.md) and [Markdown syntax](/styleguides/markdown-syntax-style.md) style guides, which should provide a general idea and an insight into the language and writing style used throughout the Buildkite Docs, as well as the Markdown syntax used (including custom formatting elements). +- [Writing](/styleguides/writing-style.md) and [Markdown syntax](/styleguides/markdown-syntax-style.md) style guides, which should provide a general idea and an insight into the language and writing style used throughout the Buildkite Docs, as well as the Markdown syntax used (including custom formatting elements). ## License