-
Notifications
You must be signed in to change notification settings - Fork 60.4k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[Style guide] Update information about formatting links (#49330)
Co-authored-by: hubwriter <[email protected]>
- Loading branch information
Showing
1 changed file
with
14 additions
and
11 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -484,19 +484,28 @@ For plain text, use linebreaks to separate paragraphs in the source (two consecu | |
## Links | ||
Introduce links consistently using a standard format that clearly indicates where we're linking. | ||
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. | ||
For any link that points to another {% data variables.product.prodname_docs %} page, use the special keyword `AUTOTITLE`. See details in the [content markup reference](https://github.com/github/docs/blob/main/contributing/content-markup-reference.md#internal-links-with-autotitle). | ||
Before adding a link, decide if someone must visit the link to understand the content. If the link is not necessary, consider removing it or including it at the end of the article as further reading. | ||
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 {% data variables.product.prodname_docs %} site, use the special keyword `AUTOTITLE` for the link text. See details in the [content markup reference](https://github.com/github/docs/blob/main/contributing/content-markup-reference.md#internal-links-with-autotitle). | ||
Do not use inline links, where words within the sentence are hyperlinked without any additional words to indicate that the sentence contains a link. This can be difficult to translate and can be harder to read. | ||
- **Use:** `OAuth2 tokens can be acquired programmatically for applications that are not websites. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)" and "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps)."` | ||
- **Avoid:** `Read [more about OAuth2](/apps/building-integrations/setting-up-and-registering-oauth-apps/). Note that OAuth2 tokens can be [acquired programmatically](/[email protected]/rest/reference/oauth-authorizations/#create-a-new-authorization), for applications that are not websites.` | ||
Usage examples: | ||
- For links to other pages: `For more information, see "[AUTOTITLE](/PATH/TO/PAGE)."` | ||
- For links to other pages: `See "[AUTOTITLE](/PATH/TO/PAGE)."` | ||
- For links to sections in other pages: `For more information, see "[AUTOTITLE](/PATH/TO/PAGE#SECTION-LINK)."` | ||
- For links to a page with a tool selected: `For more information, see the TOOLNAME documentation in "[AUTOTITLE](/PATH/TO/PAGE?tool=TOOLNAME)."` | ||
Same-page section links do **not** work with `AUTOTITLE`. Instead, type out the full header text: `For more information, see "[HEADER-TITLE](#SECTION-LINK)."` | ||
For links to external documentation, type out the full article name: `For more information, see [PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE) in the XYZ documentation.` | ||
For links to external documentation, type out the full article name: `See [PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE) in the XYZ documentation.` | ||
Do not include quotation marks within a hyperlink. | ||
|
@@ -506,15 +515,9 @@ Some best practices for using links: | |
- Do not repeat the same link more than once in the same article or under the same H2 header. | ||
- 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.) | ||
For accessibility and readability, avoid inline or midsentence links. | ||
- **Use:** `OAuth2 tokens can be acquired programmatically for applications that are not websites. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)" and "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps)."` | ||
- **Avoid:** `Read [more about OAuth2.](/apps/building-integrations/setting-up-and-registering-oauth-apps/) Note that OAuth2 tokens can be [acquired programmatically](/[email protected]/rest/reference/oauth-authorizations/#create-a-new-authorization), for applications that are not websites.` | ||
For more information on links and accessibility, see “[Links](https://readabilityguidelines.co.uk/content-design/links/)” in the Readability Guidelines project. | ||
### Links between versions | ||
Sometimes, you need to link from one version of GitHub Docs to another. When you want to link to a different version of the _same_ page, you should use the `currentArticle` property. | ||
Sometimes, you need to link from one version of {% data variables.product.prodname_docs %} to another. When you want to link to a different version of the _same_ page, you should use the `currentArticle` property. | ||
For example, the Free, Pro, & Team version of "[AUTOTITLE](/organizations/managing-organization-settings/managing-the-publication-of-github-pages-sites-for-your-organization)" might link to the {% data variables.product.prodname_ghe_cloud %} version of the same article like this: | ||
|