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 theYAML 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, seelib/frontmatter.ts.

• versions
• redirect_from
• title
• shortTitle
• intro
• permissions
• product
• layout
• children
• childGroups
• featuredLinks
• showMiniToc
• allowTitleToDifferFromFilename
• changelog
• defaultPlatform
• defaultTool
• learningTracks
• includeGuides
• journeyTracks
• type
• topics
• communityRedirect
• effectiveDate

versions

• Purpose: Indicates theversions to which a page applies.For more information about the different types of versioning, seeVersioning documentation.
• Type:Object. Allowable keys map to product names and can be found in theversions object inlib/frontmatter.ts.
• This frontmatter value is currentlyrequired for all pages.
• The* is used to denote all releases for the version.
• Must be present for allindex.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, seePermalinks.

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

title:Aboutyourpersonaldashboardversions:fpt:'*'ghes:'>=3.11'

Example that applies only to GitHub Enterprise Server:

title:Downloadingyourlicenseversions: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:GettingstartedwithGitHubDesktopredirect_from:-/articles/first-launch-/articles/error-github-enterprise-version-is-too-old-/articles/getting-started-with-github-for-windows

For more information, seeConfiguring redirects.

title

• Purpose: Set a human-friendly title for use in the rendered page's<title> tag and anh1 element at the top of the page.
• Type:String
• Required.

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.

Example:

title:ContributingtoprojectswithGitHubDesktopshortTitle:Contributingtoprojects

intro

• Purpose: Sets the intro for the page. This string will render after thetitle.
• Type:String
• Optional.

permissions

• Purpose: Sets the permission statement for the article. This string will render after theintro.
• Type:String
• Optional.

product

• Purpose: Sets the product callout for the article. This string will render after theintro andpermissions statement.
• Type:String
• Optional.

layout

• Purpose: Render the proper page layout.
• Type:String that matches the name of the layout.For a layout namedcomponents/landing, the value would beproduct-landing.
• Optional. If omitted,DefaultLayout is used.

children

• Purpose: Lists the relative links that belong to the product/category/map topic. For more information, seeIndex pages.
• Type:Array. Default isfalse.
• Required onindex.md pages.

childGroups

• Purpose: Renders children into groups on the homepage. For more information, seeHomepage.
• Type:Array. Default isfalse.
• Require on the homepageindex.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 thefeaturedLinks.popularHeading property to a new string.

Example:

featuredLinks:gettingStarted:-/path/to/pagestartHere:-/guides/examplepopular:-/path/to/popular/article1-/path/to/popular/article2popularHeading:AnalternateheadingtoPopular

showMiniToc

• Purpose: Indicates whether an article should show a mini table of contents (TOC) above the rest of the content. For more information, seeAutogenerated mini TOCs.
• Type:Boolean. Default istrue on articles, andfalse on map topics andindex.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 ofOrganizations instead ofOrgs. Pages with this frontmatter set totrue will not be flagged in tests or updated bysrc/content-render/scripts/reconcile-filenames-with-ids.ts.
• Type:Boolean. Default isfalse.
• Optional.

changelog

• Purpose: Render a list of items pulled fromGitHub Changelog on product landing pages (components/landing). The one exception is Education, which pulls fromhttps://github.blog/category/community/education.
• Type:Object, properties:
  • label -- must be present and corresponds to the labels used in theGitHub Changelog
  • prefix -- optional string that starts each changelog title that should be omitted in the docs feed. For example, with the prefixGitHub Actions: specified, changelog titles likeGitHub Actions: Some Title Here will render asSome 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, seeUsing 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 indata/learning-tracks/*.yml.
• Optional

includeGuides

• Purpose: Render a list of articles, filterable bytype andtopics. Only applicable when used withlayout: product-guides.
• Type:Array
• Optional.

Example:

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

journeyTracks

• Purpose: Define journeys for journey landing pages.
• Type:Array of objects with the following properties:
  • id (required): Unique identifier for the journey. The id only needs to be unique for journeys within a single journey landing page.
  • title (required): Display title for the journey (supports Liquid variables)
  • description (optional): Description of the journey (supports Liquid variables)
  • guides (required): Array of guide objects that make up this journey. Each guide object has:
    • href (required): Path to the article
    • alternativeNextStep (optional): Custom text to guide users to alternative paths in the journey. Supports Liquid variables and[AUTOTITLE].
• Only applicable when used withlayout: journey-landing.
• Optional.

Example:

journeyTracks:-id:'getting_started'title:'Getting started with GitHub Actions'description:'Learn the basics of GitHub Actions.'guides:-href:'/actions/quickstart'-href:'/actions/learn-github-actions'alternativeNextStep:'Want to skip ahead? See [AUTOTITLE](/actions/using-workflows).'-href:'/actions/using-workflows'-id:'advanced'title:'Advanced GitHub Actions'description:'Dive deeper into advanced features.'guides:-href:'/actions/using-workflows/workflow-syntax-for-github-actions'-href:'/actions/deployment/deploying-with-github-actions'

type

• Purpose: Indicate the type of article.
• Type:String, one of theoverview,quick_start,tutorial,how_to,reference,rai.
• Optional.

topics

• Purpose: Indicate the topics covered by the article. Refer to the content models for more details about adding topics. A full list of existing topics is located in theallowed topics file. If topics in article frontmatter and the allow-topics list become out of sync, thetopics CI test will fail.
• Type: Array ofStrings
• 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 forAsk the GitHub community link in the footer.
• Type:Object. Properties arename andhref.
• 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.

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 allH2s in the article. OnlyH2 headers are included in the mini TOCs. If an article usesH3 orH4 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 asectional TOC.

You can use theshowMiniToc frontmatter value, set tofalse, 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 akebab-cased version of the title you use in the article'stitle 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 addallowTitleToDifferFromFilename frontmatter.

Index pages

Index pages are the table of contents files for the Docs site. Every product, category, and map topic subdirectory has anindex.md file that provides an overview of the content and links to every child article. Eachindex.md must contain achildren frontmatter property with a list of relative links to the child pages of the product, category, or map topic. Index pages require aversions frontmatter property, and the actual value will be computed at runtime based on the versions of children articles.

Homepage

The homepage is the main Table of Contents file for the docs site. The homepage must have a complete list ofchildren, like everyIndex page but must also specify thechildGroups frontmatter property that will be highlighted in the main content area.

childGroups is an array of mappings containing aname for the group, an optionalicon for the group, and an array ofchildren. Thechildren in the array must be present in thechildren frontmatter property.

Creating new product guides pages

To create a product guides page (e.g.GitHub Actions Guide page), create or modify an existing markdown file with these specific frontmatter values:

• Use the product guides page template by referencinglayout: product-guides.
• Include the learning tracks inlearningTracks. Optional.
• Define which articles to include withincludeGuides. Optional.

If using learning tracks, they need to be defined indata/learning-tracks/*.yml.If usingincludeGuides, make sure each of the articles in this list hastopics andtype in its frontmatter.