Markdown and Liquid in GitHub Docs

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.

Available 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.

Mini TOCs do not appear on product landing pages, category landing pages, or map topic pages. You can suppress the mini TOC on a specific article by setting 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

The server rewrites these links at render time to include the current language code and version prefix. For example, when viewed in a GitHub Enterprise Server context, /actions/quickstart becomes /en/enterprise-server@3.12/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).

The rendered link text is automatically filled in with the target article’s current 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 %}

Preventing version transformations

By default, internal links are rewritten to match the current version context. To pin a link to a specific version (for example, linking to a GitHub.com-only policy page from an Enterprise article), include the version in the path:

[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:

![Screenshot of the Actions tab in repository settings.](/assets/images/help/repository/actions-tab.png)

Always include descriptive alt text. Alt text should describe what is shown in the image, not just repeat the surrounding prose.

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:

{%- ifversion ghes %}

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

With whitespace control on its own line, the source remains readable and the table renders correctly:

Column A | Column B | Column C
---------|----------|---------
For all versions | B1 | C1
{%- ifversion ghes %}
GHES only | B2 | C2
{%- endif %}
For all versions | B3 | C3

The {%- 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`

If a title contains Liquid (such as About {% data variables.product.prodname_emus %}), the filename uses the rendered text (about-enterprise-managed-users.md) and the page requires allowTitleToDifferFromFilename: true.

Content Basics

Markup & Versioning

Style & Quality

Markdown and Liquid in GitHub Docs

Frontmatter

Required and common fields

Escaping single quotes in frontmatter

The `allowTitleToDifferFromFilename` field

GitHub Flavored Markdown

Liquid templating

Available tags

Autogenerated mini TOC

Internal links and AUTOTITLE

AUTOTITLE

Linking to the current article in a different version

Preventing version transformations

Image paths

Whitespace control

Example: versioning a table row

Filenames

Build docs developers (and LLMs) love

Content Basics

Markup & Versioning

Style & Quality

Documentation Index

​Frontmatter

​Required and common fields

​Escaping single quotes in frontmatter

​The allowTitleToDifferFromFilename field

​GitHub Flavored Markdown

​Liquid templating

​Available tags

​Autogenerated mini TOC

​Internal links and AUTOTITLE

​AUTOTITLE

​Linking to the current article in a different version

​Preventing version transformations

​Image paths

​Whitespace control

​Example: versioning a table row

​Filenames

Build docs developers (and LLMs) love

Frontmatter

Required and common fields

Escaping single quotes in frontmatter

The `allowTitleToDifferFromFilename` field

GitHub Flavored Markdown

Liquid templating

Available tags

Autogenerated mini TOC

Internal links and AUTOTITLE

AUTOTITLE

Linking to the current article in a different version

Preventing version transformations

Image paths

Whitespace control

Example: versioning a table row

Filenames