---. The GitHub Docs site reads frontmatter to control rendering, navigation, versioning, and search behavior.
The full schema is validated by the test suite. See src/frame/lib/frontmatter.ts for the authoritative source.
title and versions are the only required fields. All other fields are optional unless otherwise noted.Core fields
Sets the human-readable title rendered as the
<h1> at the top of the page and in the browser <title> tag. Supports Liquid variables.An abbreviated title used in breadcrumbs and sidebar navigation. Falls back to
title if omitted.Maximum lengths by article type:| Article type | Max characters |
|---|---|
| Articles | 31 |
| Categories | 27 |
| Map topics | 30 |
A short description of the page rendered directly after the
title. Appears in search results and on parent index pages as the article summary.A statement describing the access level required to perform the tasks in this article. Rendered after the
intro.A product callout rendered after the
intro and permissions statement. Use this to flag that a feature requires a specific GitHub plan.Versioning
Declares which versions of GitHub this page applies to. Keys map to product plans; values are SemVer ranges or
All versions:Enterprise Server only, all releases:GitHub.com and GHES 2.20 or later:GHES 2.22 and 3.0 only:
'*' (all releases).Recognized keys:| Key | Product |
|---|---|
fpt | GitHub.com (Free, Pro, Team) |
ghes | GitHub Enterprise Server |
ghec | GitHub Enterprise Cloud |
A list of old URLs that should redirect to this page. Add entries when you rename, move, or consolidate articles so existing links remain valid.
Layout and navigation
Selects the page layout component. If omitted, the default article layout is used.
| Value | Use |
|---|---|
product-landing | Top-level product pages |
product-guides | Filterable guides index pages |
category-landing | Category overview pages |
journey-landing | Sequential learning path pages |
release-notes | Release notes pages |
graphql-explorer | Interactive GraphQL explorer |
inline | Minimal layout, no sidebar |
false | No layout wrapper |
Lists the relative paths of all pages directly nested under this index page. Required on every
index.md file.Groups children into named sections on the homepage. Only valid in
content/index.md. Each entry has a name, an optional icon, and a children array whose values must also appear in the top-level children field.Renders highlighted article links on product landing pages and the homepage. Supported sub-keys:
| Sub-key | Type | Description |
|---|---|---|
gettingStarted | string[] | Links in the “Get started” column |
startHere | string[] | Links in the “Start here” column |
guideCards | string[] | Links shown as guide cards |
popular | string[] | Links under the “Popular” heading |
popularHeading | string | Custom heading to replace “Popular” |
videos | { title, href }[] | Video links with custom heading via videosHeading |
Table of contents
Controls whether the auto-generated “In this article” mini TOC appears above the article body. Defaults to
true on articles and false on map topics and index.md pages.Set to false to suppress the mini TOC on a specific article:Do not add a hardcoded “In this article” section manually — the page will show duplicate TOCs.
Content classification
Declares the article type. Used to filter articles on product guides pages when
layout: product-guides is set.Allowed values: get-started, concepts, how-tos, reference, tutorials, rai, landing, homepage, other.Platform and tool defaults
Overrides the initial platform tab selection. Without this field, the platform that matches the reader’s operating system is shown. Use
linux for articles about GitHub Actions runners, which are OS-independent from the reader’s perspective.Allowed values: mac, windows, linux.Overrides the initial tool tab selection. Without this field, the GitHub web UI (
webui) is selected. User preferences override this default once a reader clicks a tool tab.Allowed values: webui, cli, desktop, curl, codespaces, vscode, importer_cli, graphql, powershell, bash, javascript.Product guides and learning tracks
Renders a list of learning tracks on a product’s sub-landing page. References learning track names defined in
data/learning-tracks/*.yml. Only applicable with layout: product-guides.An explicit list of article paths to include in a product guides page. Each article must have a
contentType for the filter UI to work. Only applicable with layout: product-guides.Defines journey tracks for
layout: journey-landing pages. Each track has an id, a title, an optional description, and a guides array. Each guide entry requires an href and accepts an optional alternativeNextStep.Changelog integration
Renders a “What’s new” feed on product landing pages by pulling recent entries from GitHub Changelog. Education pages pull from
With
https://github.blog/category/community/education instead.| Sub-key | Required | Description |
|---|---|---|
label | Yes | Matches labels used in the GitHub Changelog |
prefix | No | String prefix to strip from each changelog title in the feed |
prefix: 'GitHub Actions: ', a changelog entry titled “GitHub Actions: Reusable workflows are now GA” renders as “Reusable workflows are now GA” in the docs feed.Miscellaneous
When
true, suppresses the linter check that flags mismatches between a page’s title frontmatter and its filename. Use this when the title contains Liquid variables or punctuation that cannot appear in a filename.For example, a page with title: 'About {% data variables.product.prodname_emus %}' must be named about-enterprise-managed-users.md. Set allowTitleToDifferFromFilename: true to prevent test failures.Overrides the “Ask the GitHub community” link in the page footer with a custom name and URL. Properties:
name (string) and href (string).