Style guide

The GitHub Docs approach to style

• Our style guide aims for simplicity. Guidelines should be easy to apply to a range of scenarios.
• Decisions aren’t about what’s right or wrong according to the rules of grammar or the style guide, but about what’s best for our users. We're flexible and open to change while maintaining consistency.
• To scale the style guide as our team and documentation sets grow, and to create high-quality, meaningful content that serves users, we focus our attention on high-impact, high-value scenarios rather than attempting to comprehensively cover every style question.
• Consistency and grammatical correctness are important, but not as important as clarity and meaning.
• When making a style or structure decision, we consider the flow of information within the unit of content and the context of the information.
• When a question specific to help documentation isn’t covered by the style guide, we think it through using these principles, then make a decision. If a reviewer asks about it, we're prepared to discuss the decision.

Audit log events

We document each of the events that may appear in the audit logs for each type of account: user, organization, and enterprise.

• Security log events
• Audit log events for your organization
• Audit log events for your enterprise

When writing the description for an audit log event, describe the event that took place in a way that applies to all versions, using past tense and passive voice. Do not begin the sentence with phrases that are already implied by the context of the article, such as "Triggered by."

• Use: The visibility of a repository was changed.
• Use: Secret scanning was enabled for all new repositories.
• Avoid: An organization owner disabled a two-factor authentication requirement for the organization.
• Avoid: Triggered when a user updates which repositories a codespace can access.

Alerts

Alerts emphasize information within an article that is of special importance and justifies breaking the flow of information.

Use alerts sparingly. Do not use consecutive alerts, or more than one alert per section.

Alerts should be concise. If the information consists of more than a couple of sentences, or requires an ordered or unordered list, consider placing the information under a section heading instead.

Alert types

We use five types of alerts: Note, Tip, Important, Warning, and Caution.

Note

Provides additional context that users may need to take into account. Tasks can be accomplished without the information in note alerts, but some users in some contexts may benefit from the note.

Notes are particularly useful for communicating parenthetical information that is not central to the process being described:

• Caveats that might affect the outcome of a process, such as specific user settings.
• Products and features that are subject to changes in availability, such as those in public preview or closing down.

For example, Evaluating alerts from secret scanning uses a note to inform users that metadata for GitHub tokens is currently in public preview.

Tip

Recommendations, best practices or product hints. Tips contain non-essential information that users can follow at their discretion. Particularly useful in articles aimed at new users.

For example, Personalize your profile uses a tip alert to help users understand what to expect when they @mention an organization.

Important

Highlights key information users need to know to achieve their goal.

Warning

Highlights potential risks that a user should be aware of before starting or continuing with a task.

Warning alerts are particularly relevant for processes that occur outside the GitHub UI, such as in the command line or through an API.

For example, About SSH certificate authorities includes instructions for the command line, and uses a warning alert to inform users that once issued, certificates cannot be revoked:

Caution

Alerts users to dangerous or destructive actions that warrant extreme caution before performing, particularly where there is a security risk or potential for data loss.

Caution alerts will generally only be necessary when describing processes that occur outside the GitHub UI, such as in the command line or through an API.

Formatting alerts

We use standard formatting and colors for different types of alerts across doc sets.

Alerts are rendered using Markdown.

Note:

> [!NOTE]
> Keep this in mind.

Tip:

> [!TIP]
> Here's a suggestion.

Warning:

> [!WARNING]
> Be careful.

Caution:

> [!CAUTION]
> Be extremely careful.

Liquid syntax for alerts is still supported and may still appear in older articles, but should not be used for new alerts.

For more information on formatting alerts, see “Alerts” in Using Markdown and Liquid in GitHub Docs.

Using alerts with reusable text

Alerts frequently form part of reusable content (see Creating reusable content).

Call reusable content inside alert environments, rather than placing alert environments inside reusable Markdown files.

For example:

> [!CAUTION]
> {% data reusables.foo.bar %}
> Here is some additional optional text.

Call to action (CTA)

A CTA is a link or button prompting users to take the next step in their journey. It will send a user to a different location.

The key component of a CTA is that it helps the user to do what they were trying to do, either by guiding them to the next step or leading them to a product or feature they need.

In considering when to use a CTA, ask the following questions:

• Is there a logical or necessary next step for the user? This can be the next information they need, or a feature that would help them accomplish their task.
• Is there a business need for sending the user to that place?

We should only use a CTA when the answer to both questions is yes.

How is a CTA different from a link?

A CTA is an explicit direction to the user to take an immediate action, such as “Try Copilot for free” or “Create your own repository”. A CTA in our documentation should only lead people to a GitHub-owned domain.

For example, the CTA on Setting up a trial of GitHub Enterprise Cloud links to an enterprise sales page on GitHub.com.

Building CTAs

To build a valid CTA URL with the correct parameters, use the CTA builder script in your docs repository checkout:

npm run cta-builder

The script will guide you through an interactive process to:

• Select the appropriate GitHub product (ref_product)
  • Use github as the default when the link is not specific to a particular feature or product
• Choose the type of action (ref_type)
• Specify the formatting style (ref_style)
• Optionally select a specific plan (ref_plan)

The script provides all available options for each parameter and generates a complete, valid CTA URL at the end. Use this tool to ensure you're using current, approved values for CTA parameters.

For example, the script might generate a URL like:

https://github.com/account/enterprises/new?ref_product=ghec&ref_type=trial&ref_style=button&ref_plan=enterprise

Code

Code blocks

Keep lines in code samples to about 60 characters, to avoid requiring readers to scroll horizontally in the code block. Locate explanatory text before the code block, rather than using comments inside the code block. See Using Markdown and Liquid in GitHub Docs for more information on the syntax and formatting of code blocks.

Within code blocks:

• Specify the language of the sample after the first code fence. For a list of all supported languages, see Code languages in the github/docs repository.

• Do not use HTML to style or markup a code block.

• Style any placeholders that people need to replace with their own values in all caps.

  • Use: git checkout -b BRANCH-NAME
  • Avoid: git checkout -b <branch-name>

• Do not use command prompts like $ before the command itself. These prompts make it challenging for readers to copy and paste the command.

  • If you show a command and the command's output, comment out the output in the example.

  • Use:

    command
    # output
    

  • Avoid:

    $ command
    output
    

• If your code example includes { or } that should render, wrap that section in {% raw %} {% endraw %} to disable Liquid processing for that section.

  • Use:

    GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
    

  • Avoid:

    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    

• If your code example includes content that should be parsed, wrap that section in <pre> </pre> tags to parse rather than escape the content in the section.

Commands

Use inline code blocks to refer to short command names.

• Use: To check the status of a running cluster, use the ghe-cluster-status command.

Use command blocks for longer or more complex commands.

• Use: Enable maintenance mode according to your scheduled window by connecting to the administrative shell of any cluster node and running:

  ghe-cluster-maintenance -s
  

Do not include command prompts such as $. Avoid inline links in command names.

Outputs

If you show the output of a command, comment out the output in the example so that people can copy and paste the command and execute it without modification.

• Use:

  git lfs install
  # Git LFS initialized.
  

• Avoid:

  $ git lfs install
  > Git LFS initialized.
  

Examples

When code examples refer to a larger file, show the relevant section of the file, so that users understand how to edit their own code in context.

• Use:

on:
  schedule:
    - cron:  "40 19 * * *"

• Avoid:

schedule:
  - cron:  "40 19 * * *"

File names and directory names

Use backticks to format references to file names and directory names in a monospaced font. If a file type generally follows a specific capitalization convention, such as all caps for README files, use the established convention.

• Use: In your README.md file, add info about your repository.
• Use: In your .github/workflows/ directory, create the example-workflow.yml file.
• Avoid: In your .github/workflows/ directory, create the example-workflow.yml file.
• Avoid: Delete the example.js file.

Indentation

In YAML examples, such as actions and workflow files, use two spaces to indent lines within nested lists and block sequences.

• Use:

    steps:
      - uses: actions/checkout@v6
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python }}

To indent reusables, see data/reusables/README.md.

Scheduled workflows

Workflow runs are delayed when too many workflows run at once. Since many users copy code from GitHub Docs, we should use examples that guide users away from congested times.

• Do not use examples that run on the hour as these are the most congested times.
• Do not use examples that run more frequently than necessary. For example, instead of running every five minutes, consider if the example makes sense to run every 30 minutes instead.
• Use a different time for each example.

Emphasis

Use bold to emphasize words or parts of a sentence. Use emphasis sparingly (no more than five contiguous words), and remember that it is a visual aid for scannability for sighted users.

• Do not bold words that have other formatting applied, such as all caps for placeholder text.
• For accessibility, do not use bolding as the only way to convey meaning or emphasis.

For example:

• Use: Managed user accounts cannot create public content or collaborate outside your enterprise.
• Avoid: Next to Title, add a descriptive label for your new key.

Error messages

When you include the text of an error message from a GitHub product or interface in an article, format the text according to the interface where the message appears.

• If the message appears in GitHub's web interface, or in a graphical client app like GitHub Desktop or GitHub Mobile, treat the message like other text in the UI. For more information, see User interface text.

• If the message appears in a command-line interface, log output, or a response from an API, reproduce the text exactly and use backticks to format the message using a monospaced font.

Expiring content

In general, do not document content that will expire. Anyone who visits GitHub Docs should be confident that the information is accurate and up to date.

If you must document content that you know will expire, you can use the content linter to tag and track the content's expiration date. This will flag the content as outdated and avoids tracking expiration dates outside of the content itself. See Using the content linter for information on how to format expiring content tags.

Footnotes

Avoid using footnotes where possible. Consider instead whether you could use a alert or present the information in another way. See some examples of alternatives to footnotes from NICE.org.uk.

If you must use footnotes, use Markdown-native footnotes ([^1]). Footnote markers will be hyperlinked to the footnote reference, which will be listed at the bottom of the page with a backlink to the marker.

Note that regardless of the identifier you use (letters, words), footnotes will render as sequential numbers.

| | Mona | Ursula | Paul | Davy Jones[^1] |
|---|---|---|---|---|
|Favorite pastime| Shipping code | Tricking mermaids[^2] | Predicting sports | Haunting seafarers |
|Uses powers for good| Yes | No | Yes | No |
[^1]: Not to be confused with Davy Jones of The Monkees
[^2]: Also humans

Headers

Headers must adequately describe the content under them. Headers can either follow the guidelines for writing titles or can be written as questions. Use sentence casing for headers.

If an article has headers, the headers must start with an H2 level header. You can use H3 and H4 level headers to further organize content into related groups, but you cannot skip header levels. There must be text content between a header and subheader, such as an introduction.

• Use:

  ## HEADER (H2)
  
  TEXT
  
  ### SUBHEADER (H3)
  
  TEXT
  
  #### SUBHEADER (H4)
  
  TEXT
  

• Avoid: