[How we docs] Replace links to markdown files with links to the published versions (#42640)
This commit is contained in:
@@ -53,9 +53,9 @@ For content changes, make sure that you:
|
|||||||
|
|
||||||
- Confirm that the changes meet the user experience and goals outlined in the content design plan (if there is one).
|
- Confirm that the changes meet the user experience and goals outlined in the content design plan (if there is one).
|
||||||
- Review the content for technical accuracy.
|
- Review the content for technical accuracy.
|
||||||
- Check your changes for grammar, spelling, and adherence to the [style guide](https://github.com/github/docs/blob/main/contributing/content-style-guide.md).
|
- Check your changes for grammar, spelling, and adherence to the [AUTOTITLE](/contributing/writing-for-github-docs/style-guide).
|
||||||
- Make sure the text in your pull request will be easy to translate. For more information, see "[Translations guide for writers](https://github.com/github/docs/blob/main/contributing/translations-for-writers.md)."
|
- Make sure the text in your pull request will be easy to translate. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/writing-content-to-be-translated)."
|
||||||
- Check new or updated Liquid statements to confirm that versioning is correct. For more information, see "[Liquid helpers](https://github.com/github/docs/blob/main/contributing/liquid-helpers.md)."
|
- Check new or updated Liquid statements to confirm that versioning is correct. For more information, see "[AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/versioning-documentation)."
|
||||||
- Check the preview of any pages you have changed. A preview is automatically generated after you submit a pull request and links are added to the pull request. The preview sometimes takes several minutes before it is ready to view. Confirm that everything is rendering as expected. Checking the preview will help you identify problems such as typos, content that doesn't follow the style guide, or content that isn't rendering due to versioning problems. Make sure to check the rendered output for lists and tables, which can sometimes have problems that are difficult to identify in the Markdown.
|
- Check the preview of any pages you have changed. A preview is automatically generated after you submit a pull request and links are added to the pull request. The preview sometimes takes several minutes before it is ready to view. Confirm that everything is rendering as expected. Checking the preview will help you identify problems such as typos, content that doesn't follow the style guide, or content that isn't rendering due to versioning problems. Make sure to check the rendered output for lists and tables, which can sometimes have problems that are difficult to identify in the Markdown.
|
||||||
- If there are any failing checks in your pull request, troubleshoot them until they're all passing.
|
- If there are any failing checks in your pull request, troubleshoot them until they're all passing.
|
||||||
|
|
||||||
|
|||||||
@@ -63,7 +63,7 @@ When you're ready to stop your local server, type <kbd>Ctrl</kbd>+<kbd>C</kbd> i
|
|||||||
|
|
||||||
{% endnote %}
|
{% endnote %}
|
||||||
|
|
||||||
If you would like to read more about debugging and troubleshooting the {% data variables.product.prodname_docs %} application, see "[Troubleshooting](https://github.com/github/docs/blob/main/contributing/troubleshooting.md)" in the github/docs repository.
|
If you would like to read more about debugging and troubleshooting the {% data variables.product.prodname_docs %} application, see "[AUTOTITLE](/contributing/setting-up-your-environment-to-work-on-github-docs/troubleshooting-your-environment)" in the github/docs repository.
|
||||||
|
|
||||||
### Using browser shortcuts
|
### Using browser shortcuts
|
||||||
|
|
||||||
|
|||||||
@@ -92,7 +92,7 @@ redirect_from:
|
|||||||
- /articles/getting-started-with-github-for-windows/
|
- /articles/getting-started-with-github-for-windows/
|
||||||
```
|
```
|
||||||
|
|
||||||
See [`contributing/redirects`](https://github.com/github/docs/blob/main/contributing/redirects.md) for more info.
|
For more information, see "[AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/configuring-redirects)."
|
||||||
|
|
||||||
### `title`
|
### `title`
|
||||||
|
|
||||||
|
|||||||
@@ -161,7 +161,8 @@ Conceptual content helps people understand a feature or topic by providing a cle
|
|||||||
We create conceptual articles and conceptual sections within other articles. Most major products, features, or subjects have their own conceptual article.
|
We create conceptual articles and conceptual sections within other articles. Most major products, features, or subjects have their own conceptual article.
|
||||||
|
|
||||||
#### How to write conceptual content
|
#### How to write conceptual content
|
||||||
Use the [conceptual content template](https://github.com/github/docs/blob/main/contributing/content-templates.md#conceptual) to write a conceptual article.
|
|
||||||
|
For the conceptual content template, see "[AUTOTITLE](/contributing/writing-for-github-docs/templates#conceptual-article-template)."
|
||||||
|
|
||||||
- Describe in plain language what the feature, product, or topic is.
|
- Describe in plain language what the feature, product, or topic is.
|
||||||
- Describe its purpose and why it’s useful to the reader.
|
- Describe its purpose and why it’s useful to the reader.
|
||||||
@@ -193,7 +194,8 @@ We create referential articles and referential sections within other articles.
|
|||||||
- For smaller amounts of content or more specific information, like a list of a feature’s supported languages or hardware requirements, use referential sections in context within procedural or conceptual articles.
|
- For smaller amounts of content or more specific information, like a list of a feature’s supported languages or hardware requirements, use referential sections in context within procedural or conceptual articles.
|
||||||
|
|
||||||
#### How to write referential content
|
#### How to write referential content
|
||||||
Use the [referential content template](https://github.com/github/docs/blob/main/contributing/content-templates.md#referential) to write a referential article.
|
|
||||||
|
For the referential content template, see "[AUTOTITLE](/contributing/writing-for-github-docs/templates#referential-article-template)."
|
||||||
|
|
||||||
- Write a sentence or an entire conceptual section to introduce the referential content.
|
- Write a sentence or an entire conceptual section to introduce the referential content.
|
||||||
- Present the actual referential content clearly and consistently.
|
- Present the actual referential content clearly and consistently.
|
||||||
@@ -228,7 +230,8 @@ Procedural content helps people complete a task from start to finish while they
|
|||||||
We create procedural articles and procedural sections within larger articles.
|
We create procedural articles and procedural sections within larger articles.
|
||||||
|
|
||||||
#### How to write procedural articles
|
#### How to write procedural articles
|
||||||
Use the [procedural content template](https://github.com/github/docs/blob/main/contributing/content-templates.md#procedural) to write a procedural article.
|
|
||||||
|
For the procedural content template, see "[AUTOTITLE](/contributing/writing-for-github-docs/templates#procedural-article-template)."
|
||||||
|
|
||||||
- Follow the style guidelines for procedural steps in "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide#procedural-steps)".
|
- Follow the style guidelines for procedural steps in "[AUTOTITLE](/contributing/writing-for-github-docs/style-guide#procedural-steps)".
|
||||||
- Procedural content can get repetitive––look for opportunities to group related content into a single longer article.
|
- Procedural content can get repetitive––look for opportunities to group related content into a single longer article.
|
||||||
@@ -332,7 +335,8 @@ Quickstarts enable people to quickly complete a discrete, focused task by illust
|
|||||||
Quickstarts are useful when someone already understands the feature or product and is ready to try it out. Quickstarts are best for people who want instructions quickly without lengthy explanations of how something works or why they would want to use it.
|
Quickstarts are useful when someone already understands the feature or product and is ready to try it out. Quickstarts are best for people who want instructions quickly without lengthy explanations of how something works or why they would want to use it.
|
||||||
|
|
||||||
#### How to write a quickstart
|
#### How to write a quickstart
|
||||||
Use the [quickstart template](https://github.com/github/docs/blob/main/contributing/content-templates.md#quickstart) to create a quickstart guide.
|
|
||||||
|
For the quickstart template, see "[AUTOTITLE](/contributing/writing-for-github-docs/templates#quickstart-article-template)."
|
||||||
|
|
||||||
Contents of quickstarts:
|
Contents of quickstarts:
|
||||||
- Introduction:
|
- Introduction:
|
||||||
@@ -369,7 +373,8 @@ Tutorials help people learn about products and solve real world problems by guid
|
|||||||
Tutorials are useful when someone has a basic understanding of the product and is interested in extending their understanding to solve a specific problem. Tutorials are for people who want expert advice and a detailed discussion of best practices related to their problem. Tutorials also help people who've implemented similar solutions in the past with other products use {% data variables.product.prodname_dotcom %}. Tutorials can also help people validate whether the solution is appropriate for their needs.
|
Tutorials are useful when someone has a basic understanding of the product and is interested in extending their understanding to solve a specific problem. Tutorials are for people who want expert advice and a detailed discussion of best practices related to their problem. Tutorials also help people who've implemented similar solutions in the past with other products use {% data variables.product.prodname_dotcom %}. Tutorials can also help people validate whether the solution is appropriate for their needs.
|
||||||
|
|
||||||
#### How to write a tutorial
|
#### How to write a tutorial
|
||||||
Use the [tutorial template](https://github.com/github/docs/blob/main/contributing/content-templates.md#tutorial) to create a tutorial.
|
|
||||||
|
For the tutorial template, see "[AUTOTITLE](/contributing/writing-for-github-docs/templates#tutorial-article-template)."
|
||||||
|
|
||||||
Contents of tutorials:
|
Contents of tutorials:
|
||||||
- Introduction
|
- Introduction
|
||||||
|
|||||||
@@ -8,7 +8,7 @@ versions:
|
|||||||
|
|
||||||
{% note %}
|
{% 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 our [markup reference guide](https://github.com/github/docs/blob/main/contributing/content-markup-reference.md). For any questions about the GitHub brand, see our "[GitHub Brand Guide](https://brand.github.com)."
|
**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)."
|
||||||
|
|
||||||
{% endnote %}
|
{% endnote %}
|
||||||
|
|
||||||
@@ -58,7 +58,7 @@ Warnings and danger notices are rendered in red `{% raw %}{% warning %}{% endraw
|
|||||||
- Danger notices are dangerous actions that a user should exercise extreme caution before performing. They often involve the potential for data loss or other destructive actions.
|
- Danger notices are dangerous actions that a user should exercise extreme caution before performing. They often involve the potential for data loss or other destructive actions.
|
||||||
- Precede content with `**Danger:**`.
|
- Precede content with `**Danger:**`.
|
||||||
|
|
||||||
For more information on formatting callouts, see “Callouts” in "[Syntax and versioning for GitHub Docs](https://github.com/github/docs/blob/main/contributing/content-markup-reference.md)."
|
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)."
|
||||||
|
|
||||||
## Buttons
|
## Buttons
|
||||||
|
|
||||||
@@ -82,7 +82,7 @@ Style your CTAs using the following format.
|
|||||||
|
|
||||||
### Code blocks
|
### 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 "[Syntax and versioning for GitHub Docs](https://github.com/github/docs/blob/main/contributing/content-markup-reference.md#code-sample-syntax-highlighting)" for more information on the syntax and formatting of 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 "[AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs#code-sample-syntax-highlighting)" for more information on the syntax and formatting of code blocks.
|
||||||
|
|
||||||
Within 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](https://github.com/github/docs/blob/main/data/variables/code-languages.yml)" in the `github/docs` repository.
|
- Specify the language of the sample after the first code fence. For a list of all supported languages, see "[Code languages](https://github.com/github/docs/blob/main/data/variables/code-languages.yml)" in the `github/docs` repository.
|
||||||
@@ -1003,7 +1003,7 @@ For example in the following table, in order to make sense of the "Yes" and "No"
|
|||||||
</tr>
|
</tr>
|
||||||
</table>
|
</table>
|
||||||
|
|
||||||
To add row headers for a Markdown table, wrap the table in the Liquid tags `{% raw %}{% rowheaders %} {% endrowheaders %}{% endraw %}`. For more information about using row headers, see "[Table row headers](https://github.com/github/docs/blob/main/contributing/content-markup-reference.md#table-row-headers)" in the content markup reference.
|
To add row headers for a Markdown table, wrap the table in the Liquid tags `{% raw %}{% rowheaders %} {% endrowheaders %}{% endraw %}`. For more information about using row headers, see "[AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs#table-row-headers)."
|
||||||
|
|
||||||
### Include a value for every cell
|
### Include a value for every cell
|
||||||
Every cell in a table must contain a value. If the table has row headers, the first cell (cell A1) can be empty.
|
Every cell in a table must contain a value. If the table has row headers, the first cell (cell A1) can be empty.
|
||||||
@@ -1015,7 +1015,7 @@ If there is no data, use "None" or "Not applicable". Do not use "NA" or "N/A".
|
|||||||
For tables that use symbols:
|
For tables that use symbols:
|
||||||
|
|
||||||
- Populate all cells. For example in a permissions table, do not mark only the cells for things that require a permission.
|
- Populate all cells. For example in a permissions table, do not mark only the cells for things that require a permission.
|
||||||
- Use [octicons](https://github.com/github/docs/blob/main/contributing/content-markup-reference.md#octicons) or SVG. Do not use emoji.
|
- Use octicons or SVG. Do not use emoji. For more information about octicons, see "[AUTOTITLE]/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs#octicons)."
|
||||||
- Use a [check mark](https://primer.style/octicons/check-16) for affirmative values ("Yes", "Required", "Supported") and a [cross](https://primer.style/octicons/x-16) for negative values ("No", "Optional", "Unsupported").
|
- Use a [check mark](https://primer.style/octicons/check-16) for affirmative values ("Yes", "Required", "Supported") and a [cross](https://primer.style/octicons/x-16) for negative values ("No", "Optional", "Unsupported").
|
||||||
- Use `aria-label` to describe the meaning of the symbol, not its visual characteristics. For example, "Required", not "Check mark icon".
|
- Use `aria-label` to describe the meaning of the symbol, not its visual characteristics. For example, "Required", not "Check mark icon".
|
||||||
|
|
||||||
|
|||||||
@@ -145,7 +145,7 @@ Titles should be descriptive and follow the guidelines for titles in "[AUTOTITLE
|
|||||||
|
|
||||||
## Versioning
|
## Versioning
|
||||||
|
|
||||||
If a video is only relevant for specific {% data variables.product.prodname_dotcom %} products (Free, Pro and Team; {% data variables.product.prodname_ghe_server %}; {% data variables.product.prodname_ghe_managed %}; and {% data variables.product.prodname_ghe_cloud %}), the video must be versioned for those products. Use [Liquid](https://github.com/github/docs/blob/main/contributing/liquid-helpers.md) conditional statements to version the videos appropriately. The Liquid conditional versioning may need to be added when the content is initially created, or may need to be added when the content is updated for a feature update or {% data variables.product.prodname_enterprise %} release.
|
If a video is only relevant for specific {% data variables.product.prodname_dotcom %} products (Free, Pro and Team; {% data variables.product.prodname_ghe_server %}; {% data variables.product.prodname_ghe_managed %}; and {% data variables.product.prodname_ghe_cloud %}), the video must be versioned for those products. Use Liquid conditional statements to version the videos appropriately. The Liquid conditional versioning may need to be added when the content is initially created, or may need to be added when the content is updated for a feature update or {% data variables.product.prodname_enterprise %} release. For more information about liquid conditional statements and versioning, see "[AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/versioning-documentation)."
|
||||||
|
|
||||||
## Video hosting
|
## Video hosting
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user