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.

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.