GitHub Docs content files are written in GitHub Flavored Markdown (GFM) with Liquid templating layered on top. Every .md file in the content/ directory can use the full GFM feature set plus a set of custom Liquid tags that handle versioning, reusable content, and UI interactions.
Frontmatter
Every content file begins with a YAML frontmatter block delimited by ---. The frontmatter provides metadata that controls how the page is rendered, which versions it appears in, and how it appears in navigation.
---
title: About GitHub Actions
shortTitle: About Actions
intro: 'Use {% data variables.product.prodname_actions %} to automate, customize, and execute your software development workflows right in your repository.'
permissions: '{% data reusables.actions.actions-permissions %}'
versions:
fpt: '*'
ghes: '>=3.0'
ghec: '*'
defaultTool: cli
defaultPlatform: linux
redirect_from:
- /articles/about-github-actions
contentType: concepts
---
Required and common fields
| Field | Required | Description |
|---|
title | Yes | Page title rendered as an <h1> and in the browser tab. |
versions | Yes | Controls which product versions include the page. See Versioning. |
shortTitle | No | Abbreviated title used in breadcrumbs and navigation. Maximum 31 characters for articles. |
intro | No | Summary sentence rendered beneath the title. |
permissions | No | Permission statement rendered after the intro. |
defaultTool | No | Initial tool tab selection. One of: webui, cli, desktop, curl, codespaces, vscode, graphql, powershell, bash, javascript. |
defaultPlatform | No | Initial platform tab selection. One of: mac, windows, linux. |
redirect_from | No | Array of legacy URLs that redirect to this page. |
contentType | No | Article type: get-started, concepts, how-tos, reference, tutorials. |
The versions frontmatter field is required on every page. Omitting it will cause test failures. See Versioning for the full syntax. Escaping single quotes in frontmatter
YAML requires escaping single quotes inside single-quoted strings by doubling them:
# Two single quotes in a row escape the apostrophe
title: 'GitHub''s Billing Plans'
# Alternatively, switch to double quotes
title: "GitHub's Billing Plans"
The allowTitleToDifferFromFilename field
If a page title contains Liquid variables or punctuation that cannot appear in a filename, set this flag to true to suppress test failures:
title: 'About {% data variables.product.prodname_emus %}'
allowTitleToDifferFromFilename: true
GitHub Flavored Markdown
GitHub Docs supports the full GFM spec, including:
- Fenced code blocks with language identifiers
- Tables
- Task lists
- Strikethrough
- Autolinks
- Footnotes
Code blocks should always include a language identifier:
```yaml
versions:
fpt: '*'
ghes: '>=3.0'
```
Liquid templating
Liquid is a templating language processed server-side before the Markdown is rendered. GitHub Docs uses liquidjs with several custom tags.
| Tag | Purpose |
|---|
{% data %} | Insert a variable or reusable content block. |
{% ifversion %} | Conditionally render content based on product version. |
{% elsif %} / {% else %} / {% endif %} | Branches within {% ifversion %}. |
{% octicon %} | Render an Octicon inline. |
{% webui %} / {% endwebui %} | Show content only in the Web UI tool tab. |
{% cli %} / {% endcli %} | Show content only in the CLI tool tab. |
{% mac %} / {% endmac %} | Show content only on the macOS platform tab. |
{% windows %} / {% endwindows %} | Show content only on the Windows platform tab. |
{% linux %} / {% endlinux %} | Show content only on the Linux platform tab. |
{% note %} / {% endnote %} | Render an informational callout. |
{% warning %} / {% endwarning %} | Render a warning callout. |
{% tip %} / {% endtip %} | Render a tip callout. |
Autogenerated mini TOC
Every article page automatically generates an “In this article” section above the content body. This mini table of contents links to every H2 heading in the file.
Only H2 headers appear in the mini TOC. H3 and H4 headings are not included. Do not manually add an “In this article” section — it creates a duplicate.
showMiniToc: false in frontmatter.
Internal links and AUTOTITLE
Internal links must start with a product ID and use the full filepath without the file extension:
/actions/creating-actions/about-custom-actions
/github-cli/github-cli/about-github-cli
/actions/quickstart becomes /en/[email protected]/actions/quickstart.
AUTOTITLE
To avoid duplicating article titles in link text and to ensure titles stay current as articles are renamed, use the AUTOTITLE keyword as the link text:
For more information, see [AUTOTITLE](/actions/quickstart).
title frontmatter value.
Linking to the current article in a different version
Use the currentArticle property to create a cross-version link that stays valid even if the article URL changes:
{% ifversion fpt %}
For more information, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/{{ currentArticle }}).
{% endif %}
[GitHub's Terms of Service](/free-pro-team@latest/github/site-policy/github-terms-of-service)
Image paths
Images are stored under /assets/ and must be referenced using their full path including the file extension:
Whitespace control
When Liquid tags appear inside Markdown lists or tables, the extra newlines they introduce can break the rendered output. Use the hyphen (-) modifier on either or both sides of a Liquid tag to strip the adjacent whitespace:
Example: versioning a table row
Without whitespace control, inserting a Liquid conditional mid-table breaks the table:
Column A | Column B | Column C
---------|----------|---------
For all versions | B1 | C1{% ifversion ghes %}
GHES only | B2 | C2{% endif %}
For all versions | B3 | C3
Column A | Column B | Column C
---------|----------|---------
For all versions | B1 | C1
{%- ifversion ghes %}
GHES only | B2 | C2
{%- endif %}
For all versions | B3 | C3
{%- strips the newline to the left of the tag, preventing an empty line from appearing between table rows.
Filenames
Article filenames are kebab-case versions of the article title frontmatter. For example:
| Title | Filename |
|---|
About GitHub CLI | about-github-cli.md |
Contributing to projects with GitHub Desktop | contributing-to-projects-with-github-desktop.md |
GitHub's Billing Plans | githubs-billing-plans.md |
About {% data variables.product.prodname_emus %}), the filename uses the rendered text (about-enterprise-managed-users.md) and the page requires allowTitleToDifferFromFilename: true.