Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarify callout options and update to markdown from Liquid #33929

Merged
merged 12 commits into from
Jul 12, 2024
+59 −93
Merged

Clarify callout options and update to markdown from Liquid #33929

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
6192642
Update callouts to markdown
emangulo Jul 10, 2024
7e1b1c4
Update Alert to Callout title
emangulo Jul 10, 2024
dfb0717
Add Important callout as an option
emangulo Jul 10, 2024
e4a2425
Update callout to markdown syntax
emangulo Jul 10, 2024
4a51213
Align style guide to alert instead of callout
emangulo Jul 12, 2024
75bddf3
Update alert section in style guide
emangulo Jul 12, 2024
9f2f358
Apply suggestions. Remove Important alert from style guide
emangulo Jul 12, 2024
503b927
Remove double blank line for linter
emangulo Jul 12, 2024
05f5f0c
Update callout section to alert section
emangulo Jul 12, 2024
d57b6d6
Merge branch 'main' into main
ethanpalm Jul 12, 2024
e3839ee
Update link anchors
ethanpalm Jul 12, 2024
fdeb188
Update link anchor
ethanpalm Jul 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 33 additions & 36 deletions content/contributing/style-guide-and-content-model/style-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,8 @@ redirect_from:
- /contributing/writing-for-github-docs/style-guide
---

{% note %}

**Note:** These guidelines are specific to {% data variables.product.company_short %}'s documentation. For general style questions or guidance on topics not covered here, see the [Microsoft Style Guide](https://docs.microsoft.com/style-guide/welcome/). For markup specific to source content on docs.github.com, see "[AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs)." For any questions about the GitHub brand, see our "[GitHub Brand Guide](https://brand.github.com)."<!-- markdownlint-disable-line search-replace -->

{% endnote %}
> [!NOTE]
> These guidelines are specific to {% data variables.product.company_short %}'s documentation. For general style questions or guidance on topics not covered here, see the [Microsoft Style Guide](https://docs.microsoft.com/style-guide/welcome/). For markup specific to source content on docs.github.com, see "[AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs)." For any questions about the GitHub brand, see our "[GitHub Brand Guide](https://brand.github.com)."<!-- markdownlint-disable-line search-replace -->
## The {% data variables.product.prodname_docs %} approach to style

Expand All @@ -37,30 +34,21 @@ When writing the description for an audit log event, describe the event that too
* **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.

## Callouts

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

Use callouts sparingly. Do not use consecutive callouts, or more than one callout per section.
Alerts emphasize information within an article that is of special importance and justifies breaking the flow of information.

Callouts 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.

### Callout types

There are four types of callouts: tip, note, warning, and caution.

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

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.
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.

For example, "[AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/personalizing-your-profile)" uses a tip callout to help users understand what to expect when they @mention an organization.
### Alert types

> [!TIP]
> When you @mention an organization, only those that you're a member of will autocomplete. You can still @mention organizations that you're not a member of, like a previous employer, but the organization name won't autocomplete for you.
We use four types of alerts: Note, Tip, Warning, and Caution.

#### Note

Provides additional context that users may need to take into account. Tasks can be accomplished without the information in note callouts, but some users in some contexts may benefit from the 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.
Expand All @@ -71,13 +59,22 @@ For example, "[AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-se
> [!NOTE]
> Metadata for {% data variables.product.prodname_dotcom %} tokens is currently in public beta and subject to change.
#### 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, "[AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/personalizing-your-profile)" uses a tip alert to help users understand what to expect when they @mention an organization.

> [!TIP]
> When you @mention an organization, only those that you're a member of will autocomplete. You can still @mention organizations that you're not a member of, like a previous employer, but the organization name won't autocomplete for you.
#### Warning

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

Warning callouts are particularly relevant for processes that occur outside the {% data variables.product.prodname_dotcom %} UI, such as in the command line or through an API.
Warning alerts are particularly relevant for processes that occur outside the {% data variables.product.prodname_dotcom %} UI, such as in the command line or through an API.

For example, "[AUTOTITLE](/enterprise-cloud@latest/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities)" includes instructions for the command line, and uses a warning callout to alert users that once issued, certificates cannot be revoked:
For example, "[AUTOTITLE](/enterprise-cloud@latest/organizations/managing-git-access-to-your-organizations-repositories/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:

> [!WARNING]
> After a certificate has been signed and issued, the certificate cannot be revoked. Make sure to use the -V flag to configure a lifetime for the certificate, or the certificate can be used indefinitely.
Expand All @@ -86,26 +83,26 @@ For example, "[AUTOTITLE](/enterprise-cloud@latest/organizations/managing-git-ac

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 callouts will generally only be necessary when describing processes that occur outside the {% data variables.product.prodname_dotcom %} UI, such as in the command line or through an API.
Caution alerts will generally only be necessary when describing processes that occur outside the {% data variables.product.prodname_dotcom %} UI, such as in the command line or through an API.

### Formatting callouts
### Formatting alerts

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

Callouts are rendered using Markdown.
Alerts are rendered using Markdown.

Tip:
Note:

```markdown
> [!TIP]
> Here's a suggestion.
> [!NOTE]
> Keep this in mind.
```

Note:
Tip:

```markdown
> [!NOTE]
> Keep this in mind.
> [!TIP]
> Here's a suggestion.
```

Warning:
Expand All @@ -122,9 +119,9 @@ Caution:
> Be extremely careful.
```

Liquid syntax for callouts is still supported and may still appear in older articles, but should not be used for new callouts.
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 callouts, see “Callouts” in "[AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs#callout-tags)."
For more information on formatting alerts, see “Alerts” in "[AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs#alerts)."

## Buttons

Expand Down Expand Up @@ -302,7 +299,7 @@ If you must document content that you know will expire, you can use the content

## Footnotes

Avoid using footnotes where possible. Consider instead whether you could use a [callout](#callouts) or present the information in another way. See some [examples of alternatives to footnotes from NICE.org.uk](https://www.nice.org.uk/corporate/ecd6/chapter/footnotes).
Avoid using footnotes where possible. Consider instead whether you could use a [alert](#alerts) or present the information in another way. See some [examples of alternatives to footnotes from NICE.org.uk](https://www.nice.org.uk/corporate/ecd6/chapter/footnotes).

If you must use footnotes, use [Markdown-native footnotes](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#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.

Expand Down
14 changes: 7 additions & 7 deletions ...ontributing/writing-for-github-docs/using-markdown-and-liquid-in-github-docs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,29 +48,29 @@ This content is displayed on the {% data variables.product.prodname_docs %} site
This is another paragraph in the list.
1. This is the next item.

## Callout tags
## Alerts

Callouts highlight important information that users need to know. We use standard formatting and colors for four different types of callouts: notes, tips, warnings, and danger notices.
Alerts highlight important information that users need to know. We use standard formatting and colors for four different types of Alerts: Note, Tip, Warning, and Caution.

For information on when to use callouts, and how to format them in Markdown, see "[AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#callouts)."
For information on when to use alerts, and how to format them in Markdown, see "[AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#alerts)."

### Examples of callouts
### Examples of alerts

```markdown
> [!NOTE] Keep this in mind.
```

```markdown
> [!NOTE]
> Generally callouts should be short.
> Generally alerts should be short.
>
> But occasionally may require more than one paragraph
```

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

> [!NOTE]
> Generally callouts should be short.
> Generally alerts should be short.
>
> But occasionally may require more than one paragraph
Expand Down
69 changes: 19 additions & 50 deletions ...ed-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,11 @@
### A third-level heading
```

![Screenshot of rendered GitHub Markdown showing sample h1, h2, and h3 headers, which descend in type size and visual weight to indicate descending hierarchy level.](/assets/images/help/writing/headings-rendered.png)

Check warning on line 24 in content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md

View workflow job for this annotation

GitHub Actions / lint-content

Images alternate text should be between 40-150 characters 

Image alternate text is 162 characters long.

When you use two or more headings, GitHub automatically generates a table of contents that you can access by clicking {% octicon "list-unordered" aria-label="The unordered list icon" %} within the file header. Each heading title is listed in the table of contents and you can click a title to navigate to the selected section.

![Screenshot of the README file in the GitHub Docs open source repository with the drop-down menu for the table of contents exposed. The table of contents icon is outlined in dark orange.](/assets/images/help/repository/headings-toc.png)

Check warning on line 28 in content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md

View workflow job for this annotation

GitHub Actions / lint-content

Images alternate text should be between 40-150 characters 

Image alternate text is 185 characters long.

## Styling text

Expand Down Expand Up @@ -53,13 +53,10 @@

Quoted text is indented, with a different type color.

![Screenshot of rendered GitHub Markdown showing sample quoted text. The quote is indented with a vertical line on the left, and its text is dark gray rather than black.](/assets/images/help/writing/quoted-text-rendered.png)

Check warning on line 56 in content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md

View workflow job for this annotation

GitHub Actions / lint-content

Images alternate text should be between 40-150 characters 

Image alternate text is 167 characters long.

{% note %}

**Note:** When viewing a conversation, you can automatically quote text in a comment by highlighting the text, then typing <kbd>R</kbd>. You can quote an entire comment by clicking {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %}, then **Quote reply**. For more information about keyboard shortcuts, see "[AUTOTITLE](/get-started/accessibility/keyboard-shortcuts)."

{% endnote %}
> [!NOTE]
> When viewing a conversation, you can automatically quote text in a comment by highlighting the text, then typing <kbd>R</kbd>. You can quote an entire comment by clicking {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %}, then **Quote reply**. For more information about keyboard shortcuts, see "[AUTOTITLE](/get-started/accessibility/keyboard-shortcuts)."

## Quoting code

Expand All @@ -69,7 +66,7 @@
Use `git status` to list all new or modified files that haven't yet been committed.
```

![Screenshot of rendered GitHub Markdown showing the appearance of characters surrounded by backticks. The words "git status" appear in a fixed-width typeface, highlighted in light gray.](/assets/images/help/writing/inline-code-rendered.png)

Check warning on line 69 in content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md

View workflow job for this annotation

GitHub Actions / lint-content

Images alternate text should be between 40-150 characters 

Image alternate text is 184 characters long.

To format code or text into its own distinct block, use triple backticks.

Expand All @@ -82,7 +79,7 @@
```
````

![Screenshot of rendered GitHub Markdown showing a code block. The words "git status," "git add," and "git commit" appear in a fixed-width typeface, highlighted in light gray.](/assets/images/help/writing/code-block-rendered.png)

Check warning on line 82 in content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md

View workflow job for this annotation

GitHub Actions / lint-content

Images alternate text should be between 40-150 characters 

Image alternate text is 173 characters long.

For more information, see "[AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks)."

Expand All @@ -96,7 +93,7 @@
The background color is `#ffffff` for light mode and `#000000` for dark mode.
```

![Screenshot of rendered GitHub Markdown showing how HEX values within backticks create small circles of color. #ffffff shows a white circle, and #000000 shows a black circle.](/assets/images/help/writing/supported-color-models-rendered.png)

Check warning on line 96 in content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md

View workflow job for this annotation

GitHub Actions / lint-content

Images alternate text should be between 40-150 characters 

Image alternate text is 173 characters long.

Here are the currently supported color models.

Expand All @@ -106,14 +103,9 @@
| RGB | <code>\`rgb(R,G,B)\`</code> | <code>\`rgb(9, 105, 218)\`</code> | ![Screenshot of rendered GitHub Markdown showing how RGB value 9, 105, 218 appears with a blue circle.](/assets/images/help/writing/supported-color-models-rgb-rendered.png) |
| HSL | <code>\`hsl(H,S,L)\`</code> | <code>\`hsl(212, 92%, 45%)\`</code> | ![Screenshot of rendered GitHub Markdown showing how HSL value 212, 92%, 45% appears with a blue circle.](/assets/images/help/writing/supported-color-models-hsl-rendered.png) |

{% note %}

**Notes:**

* A supported color model cannot have any leading or trailing spaces within the backticks.
* The visualization of the color is only supported in issues, pull requests, and discussions.

{% endnote %}
> [!NOTE]
> * A supported color model cannot have any leading or trailing spaces within the backticks.
> * The visualization of the color is only supported in issues, pull requests, and discussions.

## Links

Expand All @@ -125,11 +117,8 @@

![Screenshot of rendered GitHub Markdown showing how text within brackets, "GitHub Pages," appears as a blue hyperlink.](/assets/images/help/writing/link-rendered.png)

{% note %}

**Note:** {% data variables.product.product_name %} automatically creates links when valid URLs are written in a comment. For more information, see "[AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls)."

{% endnote %}
> [!NOTE]
> {% data variables.product.product_name %} automatically creates links when valid URLs are written in a comment. For more information, see "[AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls)."

## Section links

Expand All @@ -149,11 +138,8 @@

{% data variables.product.product_name %} supports embedding images into your issues, pull requests{% ifversion fpt or ghec %}, discussions{% endif %}, comments and `.md` files. You can display an image from your repository, add a link to an online image, or upload an image. For more information, see "[Uploading assets](#uploading-assets)."

{% note %}

**Note:** When you want to display an image that is in your repository, use relative links instead of absolute links.

{% endnote %}
> [!NOTE]
> When you want to display an image that is in your repository, use relative links instead of absolute links.

Here are some examples for using relative links to display an image.

Expand All @@ -165,11 +151,8 @@
| In a `.md` file in another repository | `/../../../../github/docs/blob/main/assets/images/electrocat.png` |
| In issues, pull requests and comments of another repository | `../../../github/docs/blob/main/assets/images/electrocat.png?raw=true` |

{% note %}

**Note**: The last two relative links in the table above will work for images in a private repository only if the viewer has at least read access to the private repository that contains these images.

{% endnote %}
> [!NOTE]
> The last two relative links in the table above will work for images in a private repository only if the viewer has at least read access to the private repository that contains these images.

For more information, see "[Relative Links](#relative-links)."

Expand Down Expand Up @@ -217,15 +200,12 @@
- Second nested list item
```

{% note %}

**Note**: In the web-based editor, you can indent or dedent one or more lines of text by first highlighting the desired lines and then using <kbd>Tab</kbd> or <kbd>Shift</kbd>+<kbd>Tab</kbd> respectively.

{% endnote %}
> [!NOTE]
> In the web-based editor, you can indent or dedent one or more lines of text by first highlighting the desired lines and then using <kbd>Tab</kbd> or <kbd>Shift</kbd>+<kbd>Tab</kbd> respectively.

![Screenshot of Markdown in {% data variables.product.prodname_vscode %} showing how indented bullets align vertically with the first letter of the text lines above them.](/assets/images/help/writing/nested-list-alignment.png)

![Screenshot of rendered GitHub Markdown showing a numbered item followed by a bulleted item nested one level to the right, and another bulleted item nested yet further to the right.](/assets/images/help/writing/nested-list-example-1.png)

Check warning on line 208 in content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md

View workflow job for this annotation

GitHub Actions / lint-content

Images alternate text should be between 40-150 characters 

Image alternate text is 180 characters long.

To create a nested list in the comment editor on {% data variables.product.product_name %}, which doesn't use a monospaced font, you can look at the list item immediately above the nested list and count the number of characters that appear before the content of the item. Then type that number of space characters in front of the nested list item.

Expand All @@ -246,7 +226,7 @@
- Second nested list item
```

![Screenshot of rendered GitHub Markdown showing a list item prefaced by the number 100 followed by a bulleted item nested one level to the right, and another bulleted item nested yet further to the right.](/assets/images/help/writing/nested-list-example-2.png)

Check warning on line 229 in content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md

View workflow job for this annotation

GitHub Actions / lint-content

Images alternate text should be between 40-150 characters 

Image alternate text is 203 characters long.

For more examples, see the [GitHub Flavored Markdown Spec](https://github.github.com/gfm/#example-265).

Expand All @@ -264,11 +244,8 @@

You can mention a person or [team](/organizations/organizing-members-into-teams) on {% data variables.product.product_name %} by typing <kbd>@</kbd> plus their username or team name. This will trigger a notification and bring their attention to the conversation. People will also receive a notification if you edit a comment to mention their username or team name. For more information about notifications, see "[AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications)."

{% note %}

**Note:** A person will only be notified about a mention if the person has read access to the repository and, if the repository is owned by an organization, the person is a member of the organization.

{% endnote %}
> [!NOTE]
> A person will only be notified about a mention if the person has read access to the repository and, if the repository is owned by an organization, the person is a member of the organization.

`@github/support What do you think about these updates?`

Expand Down Expand Up @@ -328,13 +305,8 @@

![Screenshot of rendered Markdown showing superscript numbers used to indicate footnotes, along with optional line breaks inside a note.](/assets/images/help/writing/footnote-rendered.png)

{% note %}

**Note**: The position of a footnote in your Markdown does not influence where the footnote will be rendered. You can write a footnote right after your reference to the footnote, and the footnote will still render at the bottom of the Markdown.

Footnotes are not supported in wikis.

{% endnote %}
> [!NOTE]
> The position of a footnote in your Markdown does not influence where the footnote will be rendered. You can write a footnote right after your reference to the footnote, and the footnote will still render at the bottom of the Markdown. Footnotes are not supported in wikis.

{% ifversion markdown-alerts %}

Expand Down Expand Up @@ -383,15 +355,12 @@

`Let's rename \*our-new-project\* to \*our-old-project\*.`

![Screenshot of rendered GitHub Markdown showing how backslashes prevent the conversion of asterisks to italics. The text reads, "Let's rename our-new-project to our-old-project."](/assets/images/help/writing/escaped-character-rendered.png)

Check warning on line 358 in content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md

View workflow job for this annotation

GitHub Actions / lint-content

Images alternate text should be between 40-150 characters 

Image alternate text is 177 characters long.

For more information on backslashes, see Daring Fireball's "[Markdown Syntax](https://daringfireball.net/projects/markdown/syntax#backslash)."

{% note %}

**Note**: The Markdown formatting will not be ignored in the title of an issue or a pull request.

{% endnote %}
> [!NOTE]
> The Markdown formatting will not be ignored in the title of an issue or a pull request.

## Disabling Markdown rendering

Expand Down
Loading