jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-19 18:10:59 -05:00
Code Issues Projects Releases Wiki Activity

Update internal docs about links (#27136)

Browse Source 
* Document the existence of legacy filepaths in links

* Add examples of how links are formed

* Add convention for linking to section within an article

* Clarify "local links"
This commit is contained in:
Ethan Palm
2022-04-22 13:33:04 -07:00
committed by GitHub
parent 8dd4b7c0ab
commit a9bf789613
2 changed files with 16 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
content/README.md
View File

@@ -336,7 +336,11 @@ Just add a hyphen on either the left, right, or both sides to indicate that ther
## Links and image paths
Local links must start with a product ID (like `/actions` or `/admin`), and image paths must start with `/assets`. The links to Markdown pages undergo some transformations on the server side to match the current page's language and version. The handling for these transformations lives in [`lib/render-content/plugins/rewrite-local-links`](lib/render-content/plugins/rewrite-local-links.js).
Links to docs in the `docs-internal` repository must start with a product ID (like `/actions` or `/admin`) and contain the entire filepath, but not the file extension. For example, `/actions/creating-actions/about-custom-actions`.
Image paths must start with `/assets` and contain the entire filepath including the file extension. For example, `/assets/images/help/settings/settings-account-delete.png`.
The links to Markdown pages undergo some transformations on the server side to match the current page's language and version. The handling for these transformations lives in [`lib/render-content/plugins/rewrite-local-links`](lib/render-content/plugins/rewrite-local-links.js).
For example, if you include the following link in a content file:
@@ -364,6 +368,12 @@ Sometimes you want to link to a Dotcom-only article in Enterprise content and yo
Sometimes the canonical home of content moves outside the docs site. None of the links included in [`lib/redirects/external-sites.json`](/lib/redirects/external-sites.json) get rewritten. See [`contributing/redirects.md`](/contributing/redirects.md) for more info about this type of redirect.
### Legacy filepaths and redirects for links
Our docs contain links that use legacy filepaths such as `/article/article-name` or `/github/article-name`. Our docs also contain links that refer to articles by past names. Both of these link types function properly because of redirects, but they are bugs.
When you add a link to an article, use the current filepath and article name.
### Index pages
Index pages are the Table of Contents files for the docs site. Every product, category, and map topic subdirectory has an `index.md` that serves as the landing page. Each `index.md` must contain a `children` frontmatter property with a list of relative links to the child pages of the product, category, or map topic.

6
contributing/content-style-guide.md
View File

@@ -230,7 +230,11 @@ 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: "For more information, see X [or "Page/article title"] in the X documentation." Do not include quotation marks within a hyperlink.
Introduce links consistently using a standard format that clearly indicates where we’re linking.
For links to other articles in the GitHub docs: `For more information, see "[Page or article title]()."`
For links to another section in the same article: `For more information, see "[Header text]()."`
For links to external documentation: `For more information, see [Page or article title]() in the X documentation.`
Do not include quotation marks within a hyperlink.
Links should be meaningful and provide high value to the user’s journey - link out carefully. Move links that are helpful but not necessary to an article’s further reading section. Do not repeat the same link more than once in the same article or under the same H2 header.