Markdown and Liquid in GitHub Docs

An overview of GitHub Flavored Markdown, Liquid templating, frontmatter, links, images, and whitespace control used in GitHub Docs content files.

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.