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 in the GitHub Enterprise Cloud documentation

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.

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@v5
      - 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:

  ## HEADER (H2)
  
  #### SUBHEADER (H4)
  

Each header at the same level on a page must be unique.

• Use:

  ## Examples  (H2)
  
  TEXT
  
  ### Prompts for writing code (H3)
  
  TEXT
  
  ### Prompts for writing tests (H3)
  
  TEXT
  

• Use:

  ## Prompts for writing code (H2)
  
  TEXT
  
  ### Example (H3)
  
  TEXT
  
  ## Prompts for writing tests (H2)
  
  TEXT
  
  ### Example (H3)
  
  TEXT
  

• Avoid:

  ## Example prompts (H2)
  
  TEXT
  
  ### Example (H3)
  
  TEXT
  
  ### Example (H3)
  
  TEXT
  

Images

We use static images including screenshots, diagrams, and graphs throughout the docs to complement textual information.

Do not use animated GIFs in the docs.

Alt text

Every image must include alt text providing a textual equivalent of the visual information.

• Express the core idea or meaning of the image, rather than describing it literally.
• Use 40–150 characters.
• End with a punctuation mark. This should generally be a period unless the alt text is describing an image of text that ends with other punctuation, such as a question mark or exclamation point.
• Don't start with "Image…" or "Graphic…". Screen readers say this automatically.
• Do begin with the type of graphic: "Screenshot of…" or "Diagram that shows…"
• Follow standard language used to describe UI elements in article text.
• Put multi-word titles, such as names of menu items, in double quotation marks ("").
• If an area of the image is visually highlighted, describe how. This enables screen-reader users to understand and describe to a sighted friend/colleague what to look for from a visual language standpoint.

Alt text for screenshots

Alt text provides a short description of a screenshot's content to benefit people who cannot see it.

• Alt text only needs to include the most relevant elements of an image, not every detail.
• Alt text is not intended to provide instructions for using the GitHub interface. These should be included in accompanying article text.

Format

Screenshot of the Product name + UI element shown. The UI element + state of the element/controls, and its keyboard shortcut XYZ, are outlined in dark orange.

• For Product name, use the GitHub product or feature name, such as "GitHub Actions" or "GitHub repository," rather than just "GitHub."
• Use a variable for the word GitHub as we do in running copy: {% data variables.product.prodname_dotcom %}
• Describe UI elements consistently with written documentation.
• Be flexible with word order when needed for clarity.
  • For example, write "Screenshot of the Debug menu in Visual Studio Code…" rather than "Screenshot of the Visual Studio Code Debug menu…," to avoid multiple nouns in a row.

Examples

Screenshot of the GitHub committers by repository table. The horizontal kebab icon and "Download CSV report" button are outlined in dark orange.

Screenshot of file options in a GitHub repository. A button with an arrow indicating a dropdown menu, labeled "Code," is outlined in dark orange.

Alt text for diagrams and graphs

Explain the information conveyed in the diagram or graph in text on the page.

Use alt text to express the core idea of the image, without duplicating the webpage text.

Example

Diagram showing a five-step process by which a GitHub Actions runner can be automatically added to named classes of runners and then requested by specific jobs.

For example, see accompanying explanation of this diagram in the Actions documentation.

Alt text for images of command-line interfaces

Do not use screenshots of command-line interfaces to convey commands and their output. Instead, directly provide the commands a user should use. For more information, see the Commands section of the style guide.

When using a screenshot of a command-line interface to show user interface elements, follow standard alt text guidelines for screenshots.

File names for images

Be descriptive when naming image files: include the name, action, and UI element in the file name. Mirror product language. Use kebab case. Do not use Liquid conditionals in file names. If replacing an image, use the exact file name.

• Use: data-pack-purchase-button.png
• Avoid: purchase_button.png
• Avoid: purchase-button.png

Screenshots

To learn about creating and versioning images, see Creating and updating screenshots.

Diagrams

To learn about creating diagrams, see Creating diagrams for GitHub Docs.

Inclusive language

As home to the largest developer community in the world, GitHub is committed to promoting diversity and inclusion in every aspect of what we do. All of our documentation is inclusive and respectful of our audience, which consists of people in widely varying circumstances from all over the planet. When we write our documentation, we use words that are inclusive, anti-racist, and accessible.

Individual words might be small, but together they can create community, belonging, and equity. Be empathetic in all word and style choices. Be accurate when referring to people and communities.

Use	Avoid
Allowlist	Whitelist
Denylist	Blacklist
Default/Main branch	Master branch

Resources about inclusive language

The Microsoft Style Guide offers resources on bias-free communication, accessibility terms, and writing for all abilities:

• Bias-free communication
• Writing for all abilities
• Accessibility terms

More resources for learning about inclusive and accessible language and style:

• MailChimp Content Style Guide:
  • Writing About People
  • Writing for Accessibility
• Readability Guidelines
• Conscious Style Guide

Keyboard shortcuts

For presenting keyboard shortcuts, follow the Microsoft Style Guide, except for the following differences:

• Use the HTML <kbd> tag for each individual key.

  • Use: <kbd>Command</kbd>+<kbd>B</kbd>
  • Avoid: Command+B

• Use full words instead of symbols for Apple modifier keys.

  • Use: Command
  • Avoid: ⌘

• Use symbols for keys of special character, not full words.

  • Use: ., ,, and →.
  • Avoid: Period, Comma, and Right arrow.

Usage highlights

Here are some usage highlights for how we present keyboard shortcuts in our documentation:

• The basic syntax is to show keys with + between key combinations, without any spaces.

  • Use: <kbd>Command</kbd>+<kbd>B</kbd>, which is rendered as Command+B.
  • Avoid: <kbd>Command</kbd> + <kbd>B</kbd> or <kbd>Command + B</kbd> which are rendered as Command + B or Command + B.

• Always capitalize letter keys for general references and keyboard shortcuts.

  • Use: Command+B
  • Avoid: Command+b.

• Use the correct modifier keys for the each operating system.

  Note: Windows and Linux have Ctrl abbreviated, whereas on Mac it is spelled in full: Control.

  • For Windows and Linux:

    • Use: Ctrl, Alt.
    • Avoid: Control

  • For Mac:

    • Use: Command, Option, Control.
    • Avoid: Cmd, ⌘, Opt, ⌥, Ctrl, ⌃

• Don't confuse key combinations with keys in a sequence.

  • Command+B indicates that the user should hold down the Command key and press the B key.
  • G I indicates that the user should press the G key, then press the I key.

• When describing a keyboard shortcut for multiple operating systems, append the operating system in brackets after the shortcut. Describe the Mac shortcut first, then Windows/Linux.

  • Use: <kbd>Command</kbd>+<kbd>B</kbd> (Mac) or <kbd>Ctrl</kbd>+<kbd>B</kbd> (Windows/Linux), presented as:

    Command+B (Mac) or Ctrl+B (Windows / Linux)

  • Avoid: <kbd>Ctrl</kbd>+<kbd>B</kbd> or <kbd>Command</kbd>+<kbd>B</kbd>, presented as:

    Ctrl+B or Command+B

Licensed content

GitHub Docs is licensed under a CC-BY license. If you reuse or modify licensed content in an article, you must make sure that the license is compatible and properly attributed.

Do not create reusables for license attributions. We must use the exact license a project is licensed under, so any attributions must be accurately written for the articles that they appear in.

If you are unsure of the legality of reusing any content, contact legal. If you are adding content with a license that is not listed here, you must receive a legal review before you can publish the content.

Attributing MIT-licensed content

If we reuse or modify content under an MIT license, we must attribute the MIT license where the content appears.

At the end of the article containing MIT-licensed content

• Create a header titled Legal notice
• Attribute where the content comes from and that it is licensed under the MIT license. Include a link to the project
• Paste the full text of the MIT license from the project that you are attributing in a codeblock

Example MIT license attribution

This text is only an example. Always use the license text from the project you are attributing.

## Legal notice

Portions have been adapted from [PROJECT](/LINK/TO/PROJECT) under the MIT license:

```
MIT License

Copyright YEAR COPYRIGHT-HOLDER

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
```

Linebreaks

For plain text, use linebreaks to separate paragraphs in the source (two consecutive linebreaks), rather than to create visual space in the source. Avoid unneeded linebreaks, especially in lists.

Links

Links are used to connect people to additional information and to progress through tasks that require reading multiple articles.

Be frugal with links. Including too many links can distract from the main content or steal people's focus. All links should be considered in the context of the user journey: why might we send someone to this link and how do we get them back on track to complete their task?

Before adding a link, decide if someone must visit the link to understand the content or be successful using GitHub.

• If the link is not necessary, remove it.
• If the link relates to the main topic of an article and lets someone continue learning, but isn't necessary to complete the task, consider moving the link to the end of the article as further reading.
• If the link takes someone to the next step in a process, include the link in a next steps section at the end of the article.
• If the link provides information that can be critical to completing a task or troubleshooting a step, include the link in the main body of the article.

Links must be consistent, accessible to as many people as possible, translatable, and clear. People need to know where a link leads to and how it relates to what they want to accomplish.

Some best practices for using links:

• Links should be meaningful and provide high value to the user’s journey. Link out thoughtfully.
• Do not repeat the same link more than once in the same article.
• Consider adding "earlier/later in this article" after a link to a section in the same article.
• Do not include the apiVersion query parameter in REST links unless you need to link to a specific calendar version of the REST docs. (This should be a rare occurrence.)

Formatting links

You can introduce links with just the verb "see" if the context makes it clear what the link is for. If the context is not clear, use a phrase or sentence to introduce the link such as "For more information, see" or "To learn more about X, see Y."

Use the title of the documentation article, or external web page, as the link text. For any link that points to another article on the GitHub Docs site, use the special keyword AUTOTITLE for the link text. See details in the