[How we docs] YAML frontmatter article (#40428)

Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Co-authored-by: Steve Guntrip <stevecat@github.com>
2025-12-21 19:06:49 -05:00 · 2023-08-11 14:59:07 -04:00
parent 7403206c13
commit ce42fe9766
4 changed files with 438 additions and 5 deletions
--- a/content/contributing/syntax-and-versioning-for-github-docs/index.md
+++ b/content/contributing/syntax-and-versioning-for-github-docs/index.md
@@ -7,6 +7,7 @@ versions:
  feature: 'contributing'
 children:
  - /versioning-documentation
+  - /using-yaml-frontmatter
  - /using-markdown-and-liquid-in-github-docs
  - /changing-an-articles-title
  - /configuring-redirects
--- a/content/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs.md
+++ b/content/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs.md
@@ -186,7 +186,7 @@ These instructions are pertinent to Windows users.
 {% endwindows %}{% endraw %}
 ```

-You can define a default platform in an article's YAML frontmatter. For more information, see the [frontmatter documentation](https://github.com/github/docs/blob/main/content/README.md#frontmatter).
+You can define a default platform in an article's YAML frontmatter. For more information, see "[AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-yaml-frontmatter#defaultplatform)."

 ## Tool tags

@@ -194,7 +194,7 @@ We occasionally need to write documentation for different tools ({% data variabl

 On rare occasions, we will add new tools. Before adding a new tool, read "[AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/creating-tool-switchers-in-articles)." To add a new tool, add an entry to the `allTools` object in [`lib/all-tools.js`](https://github.com/github/docs/blob/main/src/tools/lib/all-tools.js) as a key-value pair. The key is the tag you'll use to refer to the tool in the article, and the value is how the tool will be identified on the tool picker at the top of the article.

-You can define a default tool for an article in the YAML frontmatter. For more information, see the [frontmatter documentation](https://github.com/github/docs/blob/main/content/README.md#frontmatter).
+You can define a default tool for an article in the YAML frontmatter. For more information, see "[AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-yaml-frontmatter#defaulttool)."

 ### Example usage of tool tags

@@ -343,11 +343,64 @@ If this happens, add the following CSS style to the `<table>` HTML tag:

 For a current example of this usage, see "[AUTOTITLE](/actions/examples)."

-## Internal links with AUTOTITLE
+## Links
+
+Links to docs in the `docs` repository must start with a product ID (like `/actions` or `/admin`) and contain the entire filepath, but not the file extension. For example, `/actions/creating-actions/about-custom-actions`.
+
+Image paths must start with `/assets` and contain the entire filepath including the file extension. For example, `/assets/images/help/settings/settings-account-delete.png`.
+
+The links to Markdown pages undergo some transformations on the server side to match the current page's language and version. The handling for these transformations lives in [`lib/render-content/plugins/rewrite-local-links`](https://github.com/github/docs/blob/main/src/content-render/unified/rewrite-local-links.js).
+
+For example, if you include the following link in a content file:
+
+```
+/github/writing-on-github/creating-a-saved-reply
+```
+When viewed on {% data variables.product.prodname_dotcom_the_website %} docs, the link gets rendered with the language code:
+```
+/en/github/writing-on-github/creating-a-saved-reply
+```
+and when viewed on {% data variables.product.prodname_ghe_server %} docs, the version is included as well:
+```
+/en/enterprise-server@2.20/github/writing-on-github/creating-a-saved-reply
+```
+For more information about links, see "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide#links)."
+
+### Permalinks
+
+Because the site is dynamic, it does not build HTML files for each different version of an article. Instead it generates a "permalink" for every version of the article. It does this based on the article's [`versions` frontmatter](/contributing/syntax-and-versioning-for-github-docs/using-yaml-frontmatter#versions).
+
+{% note %}
+
+**Note**: As of early 2021, the `free-pro-team@latest` version is not included in URLs. A helper function called `lib/remove-fpt-from-path.js` removes the version from URLs.
+
+{% endnote %}
+
+For example, an article that is available in currently supported versions will have permalink URLs like the following:
+
+- `/en/get-started/quickstart/set-up-git`
+- `/en/enterprise-cloud@latest/get-started/quickstart/set-up-git`
+- `/en/enterprise-server@3.10/get-started/quickstart/set-up-git`
+- `/en/enterprise-server@3.9/get-started/quickstart/set-up-git`
+- `/en/enterprise-server@3.8/get-started/quickstart/set-up-git`
+- `/en/enterprise-server@3.7/get-started/quickstart/set-up-git`
+- `/en/enterprise-server@3.6/get-started/quickstart/set-up-git`
+
+An article that is not available in {% data variables.product.prodname_ghe_server %} will have just one permalink:
+
+- `/en/get-started/quickstart/set-up-git`
+
+{% note %}
+
+**Note:** If you are a content contributor, you don't need to worry about supported versions when adding a link to a document. Following the examples above, if you want to reference an article, you can just use its relative location: `/github/getting-started-with-github/set-up-git`.
+
+{% endnote %}
+
+### Internal links with AUTOTITLE

 When linking to another {% data variables.product.prodname_docs %} page, use standard Markdown syntax like `[]()`, but type `AUTOTITLE` instead of the page title. The {% data variables.product.prodname_docs %} application will replace `AUTOTITLE` with the title of the linked page during rendering. This special keyword is case-sensitive, so take care with your typing or the replacement will not work.

-### Example usage of internal links with AUTOTITLE
+#### Example usage of internal links with AUTOTITLE

 - `For more information, see "[AUTOTITLE](/path/to/page)."`
 - `For more information, see "[AUTOTITLE](/path/to/page#section-link)."`
@@ -359,4 +412,31 @@ When linking to another {% data variables.product.prodname_docs %} page, use sta

 {% endnote %}

-For more information about links, see "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide#links)."
+### Linking to the current article in a different version of the docs
+
+Sometimes you may want to link from an article to the same article in a different product version. For example:
+
+- You mention some functionality that is not available for free, pro, or team plans and you want to link to the {% data variables.product.prodname_ghe_cloud %} version of the same page.
+- The {% data variables.product.prodname_ghe_server %} version of an article describes a feature that shipped with that version, but site administrators can upgrade to the latest version of the feature that's in use on {% data variables.product.prodname_ghe_cloud %}.
+
+You can link directly to a different version of the page using the `currentArticle` property. This means that the link will continue to work directly even if the article URL changes.
+
+```markdown
+{% raw %}{% ifversion fpt %}For more information, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest{{ currentArticle }}).{% endif %}{% endraw %}
+```
+
+### Preventing transformations
+
+Sometimes you want to link to a Dotcom-only article in Enterprise content and you don't want the link to be Enterprise-ified. To prevent the transformation, you should include the preferred version in the path.
+
+```markdown
+"[GitHub's Terms of Service](/free-pro-team@latest/github/site-policy/github-terms-of-service)"
+```
+
+Sometimes the canonical home of content moves outside the docs site. None of the links included in [`src/redirects/lib/external-sites.json`](https://github.com/github/docs/blob/main/src/redirects/lib/external-sites.json) get rewritten. See  [`contributing/redirects.md`](https://github.com/github/docs/blob/main/contributing/redirects.md) for more info about this type of redirect.
+
+### Legacy filepaths and redirects for links
+
+Our docs contain links that use legacy filepaths such as `/article/article-name` or `/github/article-name`. Our docs also contain links that refer to articles by past names. Both of these link types function properly because of redirects, but they are bugs.
+
+When you add a link to an article, use the current filepath and article name.
--- a/content/contributing/syntax-and-versioning-for-github-docs/using-yaml-frontmatter.md
+++ b/content/contributing/syntax-and-versioning-for-github-docs/using-yaml-frontmatter.md
@@ -0,0 +1,320 @@
+---
+title: Using YAML frontmatter
+shortTitle: YAML frontmatter # Max 31 characters
+intro: 'You can use YAML frontmatter to define versioning, add metadata, and control the layout for articles.'
+product: '{% data reusables.contributing.product-note %}'
+versions:
+  feature: 'contributing'
+---
+
+## About YAML frontmatter
+
+YAML frontmatter is an authoring convention popularized by Jekyll that provides a way to add metadata to pages.
+It is a block of key-value content that lives at the top of every Markdown file within {% data variables.product.prodname_docs %}. For more information, see the [YAML frontmatter documentation](https://jekyllrb.com/docs/front-matter/).
+
+## YAML frontmatter values
+
+The following frontmatter values have special meanings and requirements for {% data variables.product.prodname_docs %}.
+There's also a schema that's used by the test suite to validate every page's frontmatter.
+For more information, see [`lib/frontmatter.js`](https://github.com/github/docs/blob/main/lib/frontmatter.js).
+
+- [`versions`](#versions)
+- [`redirect_from`](#redirect_from)
+- [`title`](#title)
+- [`shortTitle`](#shorttitle)
+- [`intro`](#intro)
+- [`permissions`](#permissions)
+- [`product`](#product)
+- [`layout`](#layout)
+- [`children`](#children)
+- [`childGroups`](#childgroups)
+- [`featuredLinks`](#featuredlinks)
+- [`showMiniToc`](#showminitoc)
+- [`allowTitleToDifferFromFilename`](#allowtitletodifferfromfilename)
+- [`changelog`](#changelog)
+- [`defaultPlatform`](#defaultplatform)
+- [`defaultTool`](#defaulttool)
+- [`learningTracks`](#learningtracks)
+- [`includeGuides`](#includeguides)
+- [`type`](#type)
+- [`topics`](#topics)
+- [`communityRedirect`](#communityredirect)
+- [`effectiveDate`](#effectivedate)
+
+### `versions`
+
+- Purpose: Indicates the [versions](https://github.com/github/docs/blob/main/lib/all-versions.js) to which a page applies.
+For more information about the different types of versioning, see "[Versioning documentation](/contributing/syntax-and-versioning-for-github-docs/versioning-documentation)."
+- Type: `Object`. Allowable keys map to product names and can be found in the `versions` object in [`lib/frontmatter.js`](https://github.com/github/docs/blob/main/lib/frontmatter.js).
+- This frontmatter value is currently **required** for all pages.
+- The `*` is used to denote all releases for the version.
+
+This frontmatter value is used by the docs site to generate "permalinks" for each version of an article. For more information, see [Permalinks](#permalinks).
+
+Example that applies to {% data variables.product.prodname_dotcom_the_website %} and recent versions of {% data variables.product.prodname_ghe_server %}:
+
+```yaml
+title: About your personal dashboard
+versions:
+  fpt: '*'
+  ghes: '>=2.20'
+```
+
+Example that applies to all supported versions of {% data variables.product.prodname_ghe_server %}, but not {% data variables.product.prodname_dotcom_the_website %}:
+
+```yaml
+title: Downloading your license
+versions:
+  ghes: '*'
+```
+
+You can also version a page for a range of releases. This would version the page for {% data variables.product.prodname_dotcom_the_website %}, and {% data variables.product.prodname_ghe_server %} versions 2.22 and 3.0 only:
+
+```yaml
+versions:
+  fpt: '*'
+  ghes: '>=2.22 <3.1'
+```
+
+### `redirect_from`
+
+- Purpose: List URLs that should redirect to this page.
+- Type: `Array`
+- Optional
+
+Example:
+
+```yaml
+title: Getting started with GitHub Desktop
+redirect_from:
+  - /articles/first-launch/
+  - /articles/error-github-enterprise-version-is-too-old/
+  - /articles/getting-started-with-github-for-windows/
+```
+
+See [`contributing/redirects`](https://github.com/github/docs/blob/main/contributing/redirects.md) for more info.
+
+### `title`
+
+- Purpose: Set a human-friendly title for use in the rendered page's `<title>` tag and an `h1` element at the top of the page.
+- Type: `String`
+- Optional. If omitted, the page `<title>` will still be set, albeit with a generic value like `GitHub.com` or `GitHub Enterprise`.
+
+### `shortTitle`
+
+- Purpose: An abbreviated variant of the page title for use in breadcrumbs and navigation elements.
+- Type: `String`
+- Optional. If omitted, `title` will be used.
+
+|Article type   |Maximum character length |
+---  |  ---  |
+|articles	     |     31 |
+|categories	  |27 |
+|map topics	  |30 |
+
+Example:
+
+```yaml
+title: Contributing to projects with GitHub Desktop
+shortTitle: Contributing to projects
+```
+
+### `intro`
+
+- Purpose: Sets the intro for the page. This string will render after the `title`.
+- Type: `String`
+- Optional.
+
+### `permissions`
+
+- Purpose: Sets the permission statement for the article. This string will render after the `intro`.
+- Type: `String`
+- Optional.
+
+### `product`
+
+- Purpose: Sets the product callout for the article. This string will render after the `intro` and `permissions` statement.
+- Type: `String`
+- Optional.
+
+### `layout`
+
+- Purpose: Render the proper page layout.
+- Type: `String` that matches the name of the layout.
+For a layout named `components/landing`, the value would be `product-landing`.
+- Optional. If omitted, `DefaultLayout` is used.
+
+### `children`
+
+- Purpose: Lists the relative links that belong to the product/category/map topic. For more information, see [Index pages](#index-pages).
+- Type: `Array`. Default is `false`.
+- Required on `index.md` pages.
+
+### `childGroups`
+
+- Purpose: Renders children into groups on the homepage. For more information, see [Homepage](#homepage).
+- Type: `Array`. Default is `false`.
+- Require on the homepage `index.md`.
+
+### `featuredLinks`
+
+- Purpose: Renders the linked articles' titles and intros on product landing pages and the homepage.
+- Type: `Object`.
+- Optional.
+
+The list of popular links are the links displayed on the landing page under the title "Popular." Alternately, you can customize the title "Popular" by setting the `featuredLinks.popularHeading` property to a new string.
+
+Example:
+
+```yaml
+featuredLinks:
+  gettingStarted:
+    - /path/to/page
+  startHere:
+    - /guides/example
+  popular:
+    - /path/to/popular/article1
+    - /path/to/popular/article2
+  popularHeading: An alternate heading to Popular
+```
+
+### `showMiniToc`
+
+- Purpose: Indicates whether an article should show a mini table of contents (TOC) above the rest of the content. For more information, see [Autogenerated mini TOCs](#autogenerated-mini-tocs).
+- Type: `Boolean`. Default is `true` on articles, and `false` on map topics and `index.md` pages.
+- Optional.
+
+### `allowTitleToDifferFromFilename`
+
+- Purpose: Indicates whether a page is allowed to have a title that differs from its filename. For example, `content/rest/reference/orgs.md` has a title of `Organizations` instead of `Orgs`. Pages with this frontmatter set to `true` will not be flagged in tests or updated by `script/reconcile-ids-with-filenames.js`.
+- Type: `Boolean`. Default is `false`.
+- Optional.
+
+### `changelog`
+
+- Purpose: Render a list of items pulled from [GitHub Changelog](https://github.blog/changelog/) on product landing pages (`components/landing`). The one exception is Education, which pulls from https://github.blog/category/community/education.
+- Type: `Object`, properties:
+  - `label` -- must be present and corresponds to the labels used in the [GitHub Changelog](https://github.blog/changelog/)
+  - `prefix` -- optional string that starts each changelog title that should be omitted in the docs feed. For example, with the prefix `GitHub Actions: ` specified, changelog titles like `GitHub Actions: Some Title Here` will render as `Some Title Here` in the docs feed.
+- Optional.
+
+### `defaultPlatform`
+
+- Purpose: Override the initial platform selection for a page. If this frontmatter is omitted, then the platform-specific content matching the reader's operating system is shown by default. This behavior can be changed for individual pages, for which a manual selection is more reasonable. For example, most {% data variables.product.prodname_actions %} runners use Linux and their operating system is independent of the reader's operating system.
+- Type: `String`, one of: `mac`, `windows`, `linux`.
+- Optional.
+
+Example:
+
+```yaml
+defaultPlatform: linux
+```
+
+### `defaultTool`
+
+- Purpose: Override the initial tool selection for a page, where the tool refers to the application the reader is using to work with GitHub (such as GitHub.com's web UI, the GitHub CLI, or GitHub Desktop) or the GitHub APIs. For more information about the tool selector, see "[AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs#tool-tags)." If this frontmatter is omitted, then the tool-specific content matching the GitHub web UI is shown by default. If a user has indicated a tool preference (by clicking on a tool tab), then the user's preference will be applied instead of the default value.
+- Type: `String`, one of: `webui`, `cli`, `desktop`, `curl`, `codespaces`, `vscode`, `importer_cli`, `graphql`, `powershell`, `bash`, `javascript`.
+- Optional.
+
+```yaml
+defaultTool: cli
+```
+
+### `learningTracks`
+- Purpose: Render a list of learning tracks on a product's sub-landing page.
+- type: `String`. This should reference learning tracks' names defined in [`data/learning-tracks/*.yml`](https://github.com/github/docs/tree/main/data/learning-tracks).
+- Optional
+
+{% note %}
+
+**Note:** the featured track is set by a specific property in the learning tracks YAML. See that [README](https://github.com/github/docs/blob/main/data/learning-tracks/README.md) for details.
+
+{% endnote %}
+
+### `includeGuides`
+- Purpose: Render a list of articles, filterable by `type` and `topics`. Only applicable when used with `layout: product-guides`.
+- Type: `Array`
+- Optional.
+
+Example:
+
+```yaml
+includeGuides:
+  - /actions/guides/about-continuous-integration
+  - /actions/guides/setting-up-continuous-integration-using-workflow-templates
+  - /actions/guides/building-and-testing-nodejs
+  - /actions/guides/building-and-testing-powershell
+```
+
+### `type`
+- Purpose: Indicate the type of article.
+- Type: `String`, one of the `overview`, `quick_start`, `tutorial`, `how_to`, `reference`.
+- Optional.
+
+### `topics`
+- Purpose: Indicate the topics covered by the article. The topics are used to filter guides on some landing pages. For example, the guides at the bottom of "[Guides for {% data variables.product.prodname_actions %}](/actions/guides#all-guides)" can be filtered by topics, and the topics are listed under the guide intro. Refer to the content models for more details about adding topics. A full list of  existing topics is located in the [allowed topics file](https://github.com/github/docs/blob/main/data/allowed-topics.js). If topics in article frontmatter and the allow-topics list become out of sync, the [topics CI test](https://github.com/github/docs/blob/main/src/search/tests/topics.js) will fail.
+- Type: Array of `String`s
+- Optional: Topics are preferred for each article, but, there may be cases where existing articles don't yet have topics, or adding a topic to a new article may not add value.
+
+### `communityRedirect`
+- Purpose: Set a custom link and link name for `Ask the GitHub community` link in the footer.
+- Type: `Object`. Properties are `name` and `href`.
+- Optional.
+
+### `effectiveDate`
+- Purpose: Set an effective date for Terms of Service articles so that engineering teams can automatically re-prompt users to confirm the terms
+- Type: `string` YEAR-MONTH-DAY e.g. 2021-10-04 is October 4th, 2021
+- Optional.
+
+{% note %}
+
+**Note:** The `effectiveDate` frontmatter value is for use by {% data variables.product.company_short %} staff only.
+
+{% endnote %}
+
+## Escaping single quotes
+
+If you see two single quotes in a row (`''`) in YAML frontmatter where you might expect to see one (`'`), this is the YAML-preferred way to escape a single quote.
+
+As an alternative, you can change the single quotes surrounding the frontmatter field to double quotes and leave interior single quotes unescaped.
+
+## Autogenerated mini TOCs
+
+Every article displays a mini table of contents (TOC), which is an autogenerated "In this article" section that includes links to all `H2`s in the article. Only `H2` headers are included in the mini TOCs. If an article uses `H3` or `H4` headers to divide information in a way that only certain sections are relevant to a particular task, you can help people navigate to the content most relevant to them by using a [sectional TOC](/contributing/writing-for-github-docs/style-guide#sectional-tocs).
+
+You can use the [`showMiniToc`](#showminitoc) frontmatter value, set to `false`, to prevent the mini TOC from showing up for an article.
+
+Mini TOCs do not appear on product landing pages, category landing pages, or map topic pages.
+
+Do not add hardcoded "In this article" sections in the Markdown source or else the page will display duplicate mini TOCs.
+
+## Filenames
+
+When adding a new article, make sure the filename is a [kebab-cased](https://en.wikipedia.org/wiki/Letter_case#Special_case_styles) version of the title you use in the article's [`title`](#title) frontmatter. This can get tricky when a title has punctuation (such as "GitHub's Billing Plans"). A test will flag any discrepancies between title and filename. To override this requirement for a given article, you can add [`allowTitleToDifferFromFilename`](#allowtitletodifferfromfilename) frontmatter.
+
+## Index pages
+
+Index pages are the Table of Contents files for the docs site. Every product, category, and map topic subdirectory has an `index.md` that serves as the landing page. Each `index.md` must contain a `children` frontmatter property with a list of relative links to the child pages of the product, category, or map topic.
+
+{% note %}
+
+**Note**: The site only knows about paths included in `children` frontmatter. If a directory or article exists but is **not** included in `children`, its path will return a 404.
+
+{% endnote %}
+
+## Homepage
+
+The homepage is the main Table of Contents file for the docs site. The homepage must have a complete list of `children`, like every [Index page](#index-pages) but must also specify the `childGroups` frontmatter property that will be highlighted in the main content area.
+
+`childGroups` is an array of mappings containing a `name` for the group, an optional `icon` for the group, and an array of `children`.  The `children` in the array must be present in the `children` frontmatter property.
+
+## Creating new product guides pages
+
+To create a product guides page (e.g. [{% data variables.product.prodname_actions %} Guide page](/actions/guides)), create or modify an existing markdown file with these specific frontmatter values:
+
+- Use the product guides page template by referencing `layout: product-guides`.
+- Include the learning tracks in [`learningTracks`](#learningtracks). Optional.
+- Define which articles to include with [`includeGuides`](#includeguides). Optional.
+
+If using learning tracks, they need to be defined in [`data/learning-tracks/*.yml`](https://github.com/github/docs/tree/main/data/learning-tracks).
+If using `includeGuides`, make sure each of the articles in this list has [`topics`](#topics) and [`type`](#type) in its frontmatter.
--- a/content/contributing/syntax-and-versioning-for-github-docs/versioning-documentation.md
+++ b/content/contributing/syntax-and-versioning-for-github-docs/versioning-documentation.md
@@ -156,6 +156,38 @@ When at least one operand must be true for the condition to be true, use the ope

 Do not use the operators `&&` or `||`. Liquid does not recognize them, and the content will not render in the intended versions.

+### Whitespace control
+
+When using Liquid conditionals in lists or tables, you can use [whitespace control](https://shopify.github.io/liquid/basics/whitespace/) characters to prevent the addition of newlines and other whitespace that would break the list or table rendering.
+
+You can add a hyphen (`-`) on either the left, right, or both sides to indicate that there should be no newline or other whitespace on that side.
+
+```
+{% raw %}{%- ifversion fpt %}{% endraw %}
+```
+
+For example, to version a table row, instead of adding liquid versioning for the row starting at the end of the previous row, like this:
+
+```
+Column A | Column B | Column C
+---------|----------|---------
+This row is for all versions | B1 | C1{% raw %}{% ifversion ghes %}{% endraw %}
+This row is for GHES only | B2 | C2{% raw %}{% endif %}{% endraw %}
+This row is for all versions | B3 | C3
+```
+
+You can include the liquid versioning on its own line and use whitespace control to strip the newline to the left of the liquid tag. This makes reading the source much easier, without breaking the rendering of the table:
+
+```
+Column A | Column B | Column C
+---------|----------|---------
+This row is for all versions | B1 | C1
+{% raw %}{%- ifversion ghes %}{% endraw %}
+This row is for GHES only | B2 | C2
+{% raw %}{%- endif %}{% endraw %}
+This row is for all versions | B3 | C3
+```
+
 ## About feature-based versioning

 When you document any new change or feature, use feature-based versioning.