This version of GitHub Enterprise Server was discontinued on 2025-04-03. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise Server. For help with the upgrade, contact GitHub Enterprise support.

Using YAML frontmatter

You can use YAML frontmatter to define versioning, add metadata, and control the layout for articles.

In this article

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 GitHub Docs. For more information, see the YAML frontmatter documentation.

YAML frontmatter values

The following frontmatter values have special meanings and requirements for GitHub 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.

versions

  • Purpose: Indicates the versions to which a page applies. For more information about the different types of versioning, see Versioning documentation.
  • Type: Object. Allowable keys map to product names and can be found in the versions object in lib/frontmatter.js.
  • This frontmatter value is currently required for all pages.
  • The * is used to denote all releases for the version.
  • Must be present for all index.md files, but actual value is computed at runtime based on the children.

This frontmatter value is used by the docs site to generate "permalinks" for each version of an article. For more information, see Permalinks.

Example that applies to Free, Pro, & Team and GitHub Enterprise Server version 3.11 and later:

title: About your personal dashboard
versions:
  fpt: '*'
  ghes: '>=3.11'

Example that applies only to GitHub Enterprise Server:

title: Downloading your license
versions:
  ghes: '*'

You can also version a page for a range of releases. This would version the page for Free, Pro, & Team, and GitHub Enterprise Server versions 3.1 and 3.2 only:

versions:
  fpt: '*'
  ghes: '>=3.1 <3.3'

redirect_from

  • Purpose: List URLs that should redirect to this page.
  • Type: Array
  • Optional

Example:

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

For more information, see Configuring redirects.

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 typeMaximum character length
articles31
categories27
map topics30

Example:

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.
  • Type: Array. Default is false.
  • Required on index.md pages.

childGroups

  • Purpose: Renders children into groups on the homepage. For more information, see Homepage.
  • Type: Array. Default is false.
  • Require on the homepage index.md.
  • 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:

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.
  • 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 src/content-render/scripts/reconcile-filenames-with-ids.js.
  • Type: Boolean. Default is false.
  • Optional.

changelog

  • Purpose: Render a list of items pulled from GitHub 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
    • 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 GitHub 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:

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 Using Markdown and Liquid in GitHub Docs. 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.
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.
  • Optional

Note

The featured track is set by a specific property in the learning tracks YAML. See that README for details.

includeGuides

  • Purpose: Render a list of articles, filterable by