GitHub Docs are written using Markdown, which is a human-friendly syntax for formatting plain text. We use the variant of Markdown called GitHub Flavored Markdown and ensure that it is compliant with CommonMark. For more information, see 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.
The content on this site uses Markdown rendering powered by /src/content-render, which is in turn built on the remark Markdown processor.
This example shows the correct way to align list items with multiple paragraphs or objects.
1. Under your repository name, click **Actions**.
This is another paragraph in the list.
1. This is the next item.
This content is displayed on the GitHub Docs site with the content under the first list item correctly aligned.
Alerts highlight important information that users need to know. For details about supported alert types, how to format them in Markdown, and information on when to use alerts, see Style guide.
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.
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 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 Annotating code examples.
```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:
GH_TOKEN: $
PR_URL: $
```
These are very similar to code blocks, but use the copilot keyword rather than the name of a programming language.
Prompt blocks should always have a copy button, added using the copy option, and may also have a Copilot button, added using the prompt option. The Copilot button gives the reader a quick way to run the prompt in Copilot Chat on GitHub.com. The copy and prompt options can be used in any order.
If you use a Copilot button, you can add context to the prompt that is sent to Copilot Chat by referencing a code block in the same article. You do this by adding id=STRING-OF-YOUR-CHOICE to the code block and ref=STRING-OF-YOUR-CHOICE to the prompt block.
Add an id to the code block whose code you want to add to the prompt as context:
```javascript id=js-age
function logPersonsAge(a, b, c) {
if (c) {
console.log(a + " is " + b + " years old.");
} else {
console.log(a + " does not want to reveal their age.");
}
}
```
Then, elsewhere in the same article, reference the id in the prompt block:
```copilot copy prompt ref=js-age
Improve the variable names in this function
```
For most inline prompts, mark these by using backticks, just like inline code.
If the prompt does not require any context, you can add a clickable Copilot icon after the prompt. This allows the reader to run the prompt in Copilot Chat on GitHub.com. To add the clickable icon, surround the prompt with Liquid syntax tags:
... you can click {% prompt %}what is git{% endprompt %} to run this ...
Octicons are icons used across GitHub’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.
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.
Some Octicons used as labels have dynamic aria-label elements that change based on the state of the UI element or a user input. For example, when someone has two security policies-Policy A and Policy B-their UI will show two trash Octicons labelled {% octicon "trash" aria-label="Delete Policy A" %} and {% octicon "trash" aria-label="Delete Policy B" %}. For dynamic aria-label elements, since we can't document the exact aria-label that people will encounter, describe the Octicon and a placeholder example of the label (for example, "{% octicon "trash" aria-label="The trash icon, labelled 'Delete YOUR-POLICY-NAME'." %}"). This will help people identify both the Octicon and how it is labelled, and give context for collaborating with people who are visually describing the Octicon.
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 Style guide.
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.
We occasionally need to write documentation that has different instructions for different tools. For example, the GitHub UI, GitHub CLI, GitHub Desktop, GitHub Codespaces, and Visual Studio Code might be able to accomplish the same task using different steps. We use tool tags to control what information is displayed for each tool.
GitHub Docs maintains tool tags for GitHub products and selected third-party extensions. See the all-tools.ts object in the github/docs repository for a list of all supported tools.
On rare occasions, we will add new tools. Before adding a new tool, read Creating tool switchers in articles. To add a new tool, add an entry to the allTools object in lib/all-tools.ts 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 Using YAML frontmatter.
{% api %}
These instructions are pertinent to API users.
{% endapi %}
{% bash %}
These instructions are pertinent to Bash shell commands.
{% endbash %}
{% cli %}
These instructions are pertinent to GitHub CLI users.
{% endcli %}
{% 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 %}
{% curl %}
These instructions are pertinent to curl commands.
{% endcurl %}
{% desktop %}
These instructions are pertinent to GitHub Desktop.
{% enddesktop %}
{% importer_cli %}
These instructions are pertinent to GitHub Enterprise Importer CLI users.
{% endimporter_cli %}
{% javascript %}
These instructions are pertinent to javascript users.
{% endjavascript %}
{% jetbrains %}
These instructions are pertinent to users of JetBrains IDEs.
{% endjetbrains %}
{% powershell %}
These instructions are pertinent to `pwsh` and `powershell` commands.
{% endpowershell %}
{% vscode %}
These instructions are pertinent to VS Code users.
{% endvscode %}
{% webui %}
These instructions are pertinent to GitHub UI users.
{% endwebui %}
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 Creating reusable content.
Every row of a table in the GitHub Docs must start and end with a pipe, |, even rows that contain only Liquid versioning.
| Where is the table located? | Does every row end with a pipe? |
| --- | --- |
| {% ifversion some-cool-feature %} |
| GitHub Docs | Yes |
| {% endif %} |
If you create a table where the first column contains headers for the table rows, wrap your table in the Liquid tag {% rowheaders %} {% endrowheaders %}. For more information on using markup for tables, see Style guide.
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 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:
Links to docs in the docs repository must start with a product ID (like /actions or /admin) and contain the entire filepath, but not the file extension. For example, /actions/creating-actions/about-custom-actions.
Image paths must start with /assets and contain the entire filepath including the file extension. For example, /assets/images/help/settings/settings-account-delete.png.
The links to Markdown pages undergo some transformations on the server side to match the current page's language and version. The handling for these transformations lives in lib/render-content/plugins/rewrite-local-links.
For example, if you include the following link in a content file:
/github/writing-on-github/creating-a-saved-reply
When viewed on GitHub Docs, the link gets rendered with the language code:
Because the site is dynamic, it does not build HTML files for each different version of an article. Instead it generates a "permalink" for every version of the article. It does this based on the article's versions frontmatter.
Note
As of early 2021, the free-pro-team@latest version is not included in URLs. A helper function called lib/remove-fpt-from-path.js removes the version from URLs.
For example, an article that is available in currently supported versions will have permalink URLs like the following:
An article that is not available in GitHub Enterprise Server will have just one permalink:
/en/get-started/git-basics/set-up-git
Note
If you are a content contributor, you don't need to worry about supported versions when adding a link to a document. Following the examples above, if you want to reference an article, you can just use its relative location: /github/getting-started-with-github/set-up-git.
When linking to another GitHub Docs page, use standard Markdown syntax like [](), but type AUTOTITLE instead of the page title. The GitHub 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.
Sometimes you may want to link from an article to the same article in a different product version. For example:
You mention some functionality that is not available for free, pro, or team plans and you want to link to the GitHub Enterprise Cloud version of the same page.
The GitHub Enterprise Server version of an article describes a feature that shipped with that version, but site administrators can upgrade to the latest version of the feature that's in use on GitHub Enterprise Cloud.
You can link directly to a different version of the page using the currentArticle property. This means that the link will continue to work directly 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 %}
Sometimes you want to link to a Dotcom-only article in Enterprise content and you don't want the link to be Enterprise-ified. To prevent the transformation, you should include the preferred version in the path.
[GitHub's Terms of Service](/free-pro-team@latest/github/site-policy/github-terms-of-service)
Our docs contain links that use legacy filepaths such as /article/article-name or /github/article-name. Our docs also contain links that refer to articles by past names. Both of these link types function properly because of redirects, but they are bugs.
When you add a link to an article, use the current filepath and article name.