jprdonnelly/docs
1
0
Fork 0
mirror of synced 2026-01-08 12:01:53 -05:00
Code Issues Projects Releases Wiki Activity

Merge pull request #51645 from github/repo-sync

Browse Source 
Repo sync
This commit is contained in:
docs-bot
2024-07-12 17:40:19 -07:00
committed by GitHub
parent 3c5a0d7ef8 68556698fb
commit b40886b701
4 changed files with 62 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
content/contributing/style-guide-and-content-model/style-guide.md
View File

@@ -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
@@ -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
## Alerts
Callouts emphasize information within an article that is of special importance and justifies breaking the flow of information.
Alerts emphasize information within an article that is of special importance and justifies breaking the flow of information.
Use callouts sparingly. Do not use consecutive callouts, or more than one callout per section.
Use alerts sparingly. Do not use consecutive alerts, or more than one alert per section.
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.
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.
### Callout types
### Alert types
There are four types of callouts: tip, note, warning, and caution.
#### 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 callout 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.
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.
@@ -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.
@@ -86,20 +83,13 @@ 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.
Tip:
```markdown
> [!TIP]
> Here's a suggestion.
```
Alerts are rendered using Markdown.
Note:
@@ -108,6 +98,13 @@ Note:
> Keep this in mind.
```
Tip:
```markdown
> [!TIP]
> Here's a suggestion.
```
Warning:
```markdown
@@ -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
@@ -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.

14
content/contributing/writing-for-github-docs/using-markdown-and-liquid-in-github-docs.md
View File

@@ -48,13 +48,13 @@ 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.
@@ -62,15 +62,15 @@ For information on when to use callouts, and how to format them in Markdown, see
```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

69
content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md
View File

@@ -55,11 +55,8 @@ 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)
{% 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
@@ -106,14 +103,9 @@ Here are the currently supported color models.
| 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
@@ -125,11 +117,8 @@ You can also create a Markdown hyperlink by highlighting the text and using the
![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
@@ -149,11 +138,8 @@ You can display an image by adding <kbd>!</kbd> and wrapping the alt text in `[
{% 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.
@@ -165,11 +151,8 @@ Here are some examples for using relative links to display an image.
| 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)."
@@ -217,11 +200,8 @@ To create a nested list using the web editor on {% data variables.product.produc
- 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)
@@ -264,11 +244,8 @@ For more information, see "[AUTOTITLE](/get-started/writing-on-github/working-wi
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?`
@@ -328,13 +305,8 @@ The footnote will render like this:
![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 %}
@@ -387,11 +359,8 @@ You can tell {% data variables.product.product_name %} to ignore (or escape) Mar
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

4
content/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax.md
View File

@@ -60,8 +60,8 @@ Query | Example
<code><<em>YYYY</em>-<em>MM</em>-<em>DD</em></code> | **[cats pushed:<2012-07-05](https://github.com/search?q=cats+pushed%3A%3C2012-07-05&type=Repositories&utf8=%E2%9C%93)** matches repositories with the word "cats" that were pushed to before July 5, 2012.
<code><=<em>YYYY</em>-<em>MM</em>-<em>DD</em></code> | **[cats created:<=2012-07-04](https://github.com/search?utf8=%E2%9C%93&q=cats+created%3A%3C%3D2012-07-04&type=Issues)** matches issues with the word "cats" that were created on or before July 4, 2012.
<code><em>YYYY</em>-<em>MM</em>-<em>DD</em>..<em>YYYY</em>-<em>MM</em>-<em>DD</em></code> | **[cats pushed:2016-04-30..2016-07-04](https://github.com/search?utf8=%E2%9C%93&q=cats+pushed%3A2016-04-30..2016-07-04&type=Repositories)** matches repositories with the word "cats" that were pushed to between the end of April and July of 2016.
<code><em>YYYY</em>-<em>MM</em>-<em>DD</em>..*</code> | **[cats created:2012-04-30..*](https://github.com/search?utf8=%E2%9C%93&q=cats+created%3A2012-04-30..*&type=Issues)** matches issues created after April 30th, 2012 containing the word "cats."
<code>*..<em>YYYY</em>-<em>MM</em>-<em>DD</em></code> | **[cats created:*..2012-07-04](https://github.com/search?utf8=%E2%9C%93&q=cats+created%3A*..2012-07-04&type=Issues)** matches issues created before July 4th, 2012 containing the word "cats."
<code><em>YYYY</em>-<em>MM</em>-<em>DD</em>..*</code> | **[cats created:2012-04-30..*](https://github.com/search?utf8=%E2%9C%93&q=cats+created%3A2012-04-30..*&type=Issues)** matches issues created on or after April 30th, 2012 containing the word "cats."
<code>*..<em>YYYY</em>-<em>MM</em>-<em>DD</em></code> | **[cats created:*..2012-07-04](https://github.com/search?utf8=%E2%9C%93&q=cats+created%3A*..2012-07-04&type=Issues)** matches issues created on or before July 4th, 2012 containing the word "cats."
{% data reusables.time_date.time_format %}