> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/github/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://github.github.com/gfm/) (GFM) with [Liquid](https://shopify.github.io/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. ```yaml theme={null} --- 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 `

` and in the browser tab. | | `versions` | Yes | Controls which product versions include the page. See [Versioning](/content/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](/content/versioning) for the full syntax. ### Escaping single quotes in frontmatter YAML requires escaping single quotes inside single-quoted strings by doubling them: ```yaml theme={null} # 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: ```yaml theme={null} title: 'About {% data variables.product.prodname_emus %}' allowTitleToDifferFromFilename: true ``` ## GitHub Flavored Markdown GitHub Docs supports the full [GFM spec](https://github.github.com/gfm/), including: * Fenced code blocks with language identifiers * Tables * Task lists * Strikethrough * Autolinks * Footnotes Code blocks should always include a language identifier: ````markdown theme={null} ```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](https://liquidjs.com/) 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](https://primer.style/foundations/icons/) 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: ```markdown theme={null} /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: ```markdown theme={null} 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: ```markdown theme={null} {% 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: ```markdown theme={null} [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: ```markdown theme={null} ![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: ```liquid theme={null} {%- ifversion ghes %} ``` ### Example: versioning a table row Without whitespace control, inserting a Liquid conditional mid-table breaks the table: ```markdown theme={null} 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: ```markdown theme={null} 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](https://en.wikipedia.org/wiki/Letter_case#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`.