docs/content/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs.md

---
title: Using Markdown and Liquid in GitHub Docs
shortTitle: Markdown and Liquid # Max 31 characters
intro: 'You can use Markdown and Liquid to format content, create reusable content, and write content for different versions on {% data variables.product.prodname_docs %}.'
product: '{% data reusables.contributing.product-note %}'
versions:
  feature: 'contributing'
---

## About using Markdown and Liquid in {% data variables.product.prodname_docs %}

{% data variables.product.prodname_docs %} are written using Markdown, which is a human-friendly syntax for formatting plain text. We use the variant of Markdown called {% data variables.product.prodname_dotcom %} Flavored Markdown and ensure that it is compliant with CommonMark. For more information, see "[AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/about-writing-and-formatting-on-github)."

We use Liquid syntax to expand the functionality to provide accessible tables, maintainable links, versioning, variables, and chunks of reusable content. For more information about Liquid, see the [Liquid documentation](https://shopify.github.io/liquid/basics/introduction/).

The content on this site uses Markdown rendering powered by [`/src/content-render`](https://github.com/github/docs/blob/main/src/content-render/README.md), which is in turn built on the [`remark`](https://remark.js.org/) Markdown processor.

## Lists

In a list item, the general rules for additional content after the first paragraph are:

- Images and subsequent paragraphs should each be on their own line and separated by a blank line.
- All subsequent lines in a list item must match up with the first text after the list marker.

### Example usage of a list

This example shows the correct way to align list items with multiple paragraphs or objects.

```markdown
1. Under your repository name, click **Actions**.

   ![Screenshot of the tabs for the "github/docs" repository. The "Actions" tab is highlighted with an orange outline.](/assets/images/help/repository/actions-tab.png)

   This is another paragraph in the list.

1. This is the next item.
```

This content is displayed on the {% data variables.product.prodname_docs %} site with the content under the first list item correctly aligned.

### Example list rendered on {% data variables.product.prodname_docs %}

1. Under your repository name, click **Actions**.

   ![Screenshot of the tabs for the "github/docs" repository. The "Actions" tab is highlighted with an orange outline.](/assets/images/help/repository/actions-tab.png)

   This is another paragraph in the list.
1. This is the next item.

## Callout tags

Callouts highlight important information that users need to know. We use standard formatting and colors for different types of callouts: notes, warnings, and danger notices. Use Liquid tags before and after the text you’d like included in the callout box.

For information on when to use callout tags, see "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide#callouts)."

### Example usage of a callout

```
{% raw %}{% note %}

**Note:** Owners and administrators can add outside collaborators to a repository.

{% endnote %}{% endraw %}
```

### Example callout rendered on {% data variables.product.prodname_docs %}

{% note %}

**Note:** Owners and administrators can add outside collaborators to a repository.

{% endnote %}

## Code sample syntax highlighting

To render syntax highlighting in command line instructions and code samples, we use triple backticks followed by the language of the sample. For a list of all supported languages, see [`code-languages.yml`](https://github.com/github/docs/blob/main/data/variables/code-languages.yml).

### Example usage of code syntax highlighting

    ```bash
    git init YOUR_REPOSITORY
    ```

Within the code sample syntax, use all uppercase text to indicate placeholder text or content that varies for each user, such as a user or repository name. By default, codeblocks will escape the content within the triple backticks. If you need to write sample code that parses the content (for example, to italicize text within `<em>` tags instead of passing the tags through literally), wrap the codeblock in `<pre>` tags.

### Code blocks with a copy button

You can also add a header that includes the name of the language and a button to copy the contents of the code block.

For example, the following code adds syntax highlighting for JavaScript and a copy button for the code sample.

#### Example usage of a copy button

    ```javascript copy
    const copyMe = true
    ```

#### Example code rendered on {% data variables.product.prodname_docs %}

```javascript copy
const copyMe = true
```

## Code sample annotations
Code sample annotations help explain longer code examples by rendering comments as annotations next to the sample code. This lets us write longer explanations of code without cluttering the code itself. Code samples with annotations are rendered in a two pane layout with the code sample on the left and the annotations on the right. The annotations are visually emphasized when someone hovers their cursor over the code example.

Code annotations only work in articles with the `layout: inline` frontmatter property. For more information on how to write and style code annotations, see "[AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/annotating-code-examples)."

### Example of an annotated code sample

    ```yaml annotate
    # The name of the workflow as it will appear in the "Actions" tab of the GitHub repository.
    name: Post welcome comment
    # The `on` keyword lets you define the events that trigger when the workflow is run.
    on:
      # Add the `pull_request` event, so that the workflow runs automatically
      # every time a pull request is created.
      pull_request:
        types: [opened]
    # Modifies the default permissions granted to `GITHUB_TOKEN`.
    permissions:
      pull-requests: write
    # Defines a job with the ID `build` that is stored within the `jobs` key.
    jobs:
      build:
        name: Post welcome comment
        # Configures the operating system the job runs on.
        runs-on: ubuntu-latest
        # The `run` keyword tells the job to execute the [`gh pr comment`](https://cli.github.com/manual/gh_pr_comment) command on the runner.
        steps:
          - run: gh pr comment $PR_URL --body "Welcome to the repository!"
            env:
              GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
              PR_URL: ${{ github.event.pull_request.html_url }}
    ```

For an example of an article that uses code annotations on {% data variables.product.prodname_docs %}, see "[AUTOTITLE](/actions/examples/using-scripts-to-test-your-code-on-a-runner)."

## Octicons

Octicons are icons used across {% data variables.product.prodname_dotcom %}’s interface. We reference Octicons when documenting the user interface and to indicate binary values in tables. Find the name of specific Octicons on the [Octicons site](https://primer.style/Octicons).

If you're referencing an Octicon that appears in the UI, identify whether the Octicon is the entire label of the UI element (for example, a button that is labeled only with "+") or whether it's only decorative, in addition to another label (for example, a button is labeled "+ Add message").

 - If the Octicon is the entire label, use your browser's developer tools to inspect the Octicon and determine what screen reader users will hear instead. Then, use that text for the `aria-label` (for example, `{% octicon "plus" aria-label="Add file" %}`). Occasionally, in the UI, the Octicon itself will not have an `aria-label`, but a surrounding element such as a `<summary>` or `<div>` tag will.
 - If the Octicon is decorative, it's likely hidden to screen readers with the `aria-hidden=true` attribute. If so, for consistency with the product, use `aria-hidden="true"` in the Liquid syntax for the Octicon in the docs as well (for example, `"{% octicon "plus" aria-hidden="true" %} Add message"`).

If you're using the Octicon in another way, such as using the "check" and "x" icons to reflect binary values in tables, use the `aria-label` to describe the meaning of the Octicon, not its visual characteristics. For example, if you're using a "x" icon in the "Supported" column of a table, use "Not supported" as the `aria-label`. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide#tables)."

### Example usage of octicons

```text
{% raw %}{% octicon "<name of Octicon>" %}
{% octicon "plus" %}
{% octicon "plus" aria-label="Add file" %}
"{% octicon "plus" aria-hidden="true" %} Add file"{% endraw %}
```

## Operating system tags

We occasionally need to write documentation for different operating systems. Each operating system may require a different set of instructions. We use operating system tags to demarcate information for each operating system.

### Example usage of operating system tags

```
{% raw %}{% mac %}

These instructions are pertinent to Mac users.

{% endmac %}{% endraw %}
```

```
{% raw %}{% linux %}

 These instructions are pertinent to Linux users.

{% endlinux %}{% endraw %}
```

```
{% raw %}{% windows %}

These instructions are pertinent to Windows users.

{% endwindows %}{% endraw %}
```

You can define a default platform in an article's YAML frontmatter. For more information, see the [frontmatter documentation](https://github.com/github/docs/blob/main/content/README.md#frontmatter).

## Tool tags

We occasionally need to write documentation for different tools ({% data variables.product.prodname_dotcom %} UI, {% data variables.product.prodname_cli %}, {% data variables.product.prodname_desktop %}, {% data variables.product.prodname_github_codespaces %}, curl, Visual Studio Code, JetBrains IDEs, {% data variables.product.prodname_importer_proper_name %} CLI, GraphQL API). Each tool may require a different set of instructions. We use tool tags to demarcate information for each tool.

On rare occasions, we will add new tools. Before adding a new tool, read "[AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/creating-tool-switchers-in-articles)." To add a new tool, add an entry to the `allTools` object in [`lib/all-tools.js`](https://github.com/github/docs/blob/main/lib/all-tools.js) as a key-value pair. The key is the tag you'll use to refer to the tool in the article, and the value is how the tool will be identified on the tool picker at the top of the article.

You can define a default tool for an article in the YAML frontmatter. For more information, see the [frontmatter documentation](https://github.com/github/docs/blob/main/content/README.md#frontmatter).

### Example usage of tool tags

```
{% raw %}{% api %}

These instructions are pertinent to API users.

{% endapi %}{% endraw %}
```

```
{% raw %}{% bash %}

These instructions are pertinent to Bash shell commands.

{% endbash %}{% endraw %}
```

```
{% raw %}{% cli %}

These instructions are pertinent to GitHub CLI users.

{% endcli %}{% endraw %}
```

```
{% raw %}{% codespaces %}

These instructions are pertinent to Codespaces users. They are mostly used outside the Codespaces docset, when we want to refer to how to do something inside Codespaces. Otherwise `webui` or `vscode` may be used.

{% endcodespaces %}{% endraw %}
```

```
{% raw %}{% curl %}

These instructions are pertinent to curl commands.

{% endcurl %}{% endraw %}
```

```
{% raw %}{% desktop %}

 These instructions are pertinent to GitHub Desktop.

{% enddesktop %}{% endraw %}
```

```
{% raw %}{% importer_cli %}

These instructions are pertinent to GitHub Enterprise Importer CLI users.

{% endimporter_cli %}{% endraw %}
```

```
{% raw %}{% javascript %}

These instructions are pertinent to javascript users.

{% endjavascript %}{% endraw %}
```

```
{% raw %}{% jetbrains %}

These instructions are pertinent to users of JetBrains IDEs.

{% endjetbrains %}{% endraw %}
```

```
{% raw %}{% powershell %}

These instructions are pertinent to `pwsh` and `powershell` commands.

{% endpowershell %}{% endraw %}
```

```
{% raw %}{% vscode %}

These instructions are pertinent to VS Code users.

{% endvscode %}{% endraw %}
```

```
{% raw %}{% webui %}

These instructions are pertinent to GitHub UI users.

{% endwebui %}{% endraw %}
```

## Reusable and variable strings of text

Reusable strings (commonly called content references or conrefs) contain content that is used in more than one place in our documentation. Creating these allows us to update the content in a single location rather than every place the string appears.

For longer strings, we use reusables, and for shorter strings, we use variables. For more information about reusables and variables, see "[AUTOTITLE](/contributing/writing-for-github-docs/creating-reusable-content)."

## Table row headers

If you create a table where the first column contains headers for the table rows, wrap your table in the Liquid tag {% raw %}`{% rowheaders %} {% endrowheaders %}`{% endraw %}. For more information on using markup for tables, see "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide#use-proper-markup-for-row-and-column-headers)."

### Example table with row headers

```
{% raw %}{% rowheaders %}

|             | Mona | Tom    | Hobbes |
|-------------|------|--------|--------|
|Type of cat  | Octo | Tuxedo | Tiger  |
|Likes to swim| Yes  | No     | No     |

{% endrowheaders %}{% endraw %}
```

### Example table without row headers

```
| Name   | Vocation         |
| ------ | ---------------- |
| Mona   | GitHub mascot    |
| Tom    | Mouse antagonist |
| Hobbes | Best friend      |
```

## Tables with codeblocks

Although using tables to contain block items, such as code blocks, is generally discouraged, occasionally it may be appropriate.

Because [tables in GitHub Flavored Markdown](https://github.github.com/gfm/#tables-extension-) cannot contain any line breaks or block-level structures, you must use HTML tags to write the table structure.

When HTML tables contain code blocks, the width of the table might exceed the regular width of page content, and then overflow into the area normally containing the mini table of contents.

If this happens, add the following CSS style to the `<table>` HTML tag:

```html
<table style="table-layout: fixed;">
```

For a current example of this usage, see "[AUTOTITLE](/actions/examples)."

## Internal links with AUTOTITLE

When linking to another {% data variables.product.prodname_docs %} page, use standard Markdown syntax like `[]()`, but type `AUTOTITLE` instead of the page title. The {% data variables.product.prodname_docs %} application will replace `AUTOTITLE` with the title of the linked page during rendering. This special keyword is case-sensitive, so take care with your typing or the replacement will not work.

### Example usage of internal links with AUTOTITLE

- `For more information, see "[AUTOTITLE](/path/to/page)."`
- `For more information, see "[AUTOTITLE](/path/to/page#section-link)."`
- `For more information, see the TOOLNAME documentation in "[AUTOTITLE](/path/to/page?tool=TOOLNAME)."`

{% note %}

**Note:** Same-page section links do not work with this keyword. Type out the full header text instead.

{% endnote %}

For more information about links, see "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide#links)."