link-002 should GuidesAPI docs Write meaningful, descriptive link text that makes sense when read out of context. Do not use generic phrases like ‘click here’ or ‘read this document’.
Links
Links carry readers between pages, so their text has to make sense on its own and their formatting has to survive rendering and screen readers. These rules cover link text, cross-reference phrasing, and how URLs and file paths appear in prose. When to cross-reference at all is covered on the refer-and-link page.
Descriptive link text
Section titled “Descriptive link text”Examples
- ✓ For setup steps, see the installation guide.
- ✗ For setup steps, click here.
Rationale
Screen-reader users and scanners read links out of context, so the text must say where the link goes; “click here” says nothing.
No bare URLs as link text
Section titled “No bare URLs as link text”link-003 should GuidesAPI docs Do not use a bare URL as link text. Use the page title or a description of the destination page.
Examples
- ✓ See the billing overview.
- ✗ See https://example.com/docs/billing.
Rationale
A raw URL is hard to read aloud and says little about the destination, so a title or description is clearer.
Short, front-loaded link text
Section titled “Short, front-loaded link text”link-004 should GuidesAPI docs Keep link text short and place important words at the beginning.
Examples
Rationale
Front-loaded, short link text is easier to scan in a list of links.
Unique link text per target
Section titled “Unique link text per target”link-005 should GuidesAPI docs Do not use the same link text in the same document for different target pages.
Examples
Rationale
Two links with the same text but different targets confuse anyone navigating by link list.
Abbreviations in link text
Section titled “Abbreviations in link text”link-014 should GuidesAPI docs If link text includes an abbreviation in parentheses, include both the long form and the abbreviation within the link text.
Examples
- ✓ Single sign-on (SSO) configuration
- ✗ Single sign-on (SSO) configuration
Rationale
Including both the long form and the abbreviation keeps the link text self-explanatory out of context.
No quotation marks around links
Section titled “No quotation marks around links”link-008 should GuidesAPI docs Do not put link text in quotation marks. When a cross-reference is a hyperlink, format it as a link only.
Examples
- ✓ See Error handling.
- ✗ See “Error handling”.
Rationale
Quotation marks around link text are redundant with the link styling and add clutter.
Punctuation outside links
Section titled “Punctuation outside links”link-007 should GuidesAPI docs Place punctuation outside link tags rather than inside them.
Examples
Rationale
Punctuation inside the link becomes part of the clickable area and can render underlined oddly.
Cross-reference phrasing
Section titled “Cross-reference phrasing”link-006 should GuidesAPI docs When introducing a standalone cross-reference sentence, use the phrase ‘For more information, see…’ or ‘For more information about [topic], see…’. Use ‘about’ (not ‘on’) and ‘see’ (not another verb).
Examples
- ✓ For more information about rate limits, see Rate limits.
- ✗ For more information on rate limits, refer to Rate limits.
Rationale
A consistent “For more information, see” phrasing is predictable and translates cleanly, and “about” avoids the directional read of “on.”
Same-page links
Section titled “Same-page links”link-013 should GuidesAPI docs When linking to a section on the same page, indicate that the link stays on the same page (‘the [Section Name] section of this document’).
Examples
- ✓ See the Authentication section of this document.
- ✗ See Authentication.
Rationale
Telling the reader a link stays on the page sets the right expectation before they click.
Signal external destinations
Section titled “Signal external destinations”link-010 should GuidesAPI docsMarketingBlog When a link leads to an external domain, communicate that fact to all readers: use descriptive link text that names or implies the external source, rendered external-link icons with accessible markup, or both. Icons are added by the site framework at render time based on URL, not by authors in source.
Examples
- ✓ See the OAuth 2.0 specification on example.org.
- ✗ See the specification.
Rationale
Readers consume content in different modes, so signaling an external destination through both descriptive text and an accessible icon reaches everyone rather than relying on a cue that some readers miss.
Opening in a new tab
Section titled “Opening in a new tab”link-009 should GuidesAPI docs Do not force links to open in a new tab or window by default. If a link must open in a new tab, inform the reader in the link text (‘opens in a new tab’).
Examples
- ✓ Status dashboard (opens in a new tab)
- ✗
<a href="https://status.example.com" target="_blank">Status dashboard</a>
Rationale
Forcing a new tab overrides the reader’s control and breaks the back button; if it is needed, saying so sets expectations.
Be selective with links
Section titled “Be selective with links”link-011 should GuidesAPI docs Be selective about links; avoid duplicate links to the same destination on a single page except where justified, such as very long pages, multiple entry points, or links to different sections of the same target.
Rationale
Duplicate links to the same place add noise and dilute the useful ones.
Inline or link
Section titled “Inline or link”link-012 should GuidesAPI docsMarketingBlog When a reader needs additional context, decide between inlining and linking based on stability and duplication risk: inline brief context for stable concepts, and link out for product-specific details and for content substantially longer than a sentence or two. If the information could change and leave the inline copy incorrect, link out.
Examples
- ✓ For the current list of supported regions, see Locations.
- ✗ The supported regions are
us-east,eu-west, andap-south.
Rationale
Inlining a stable definition saves the reader a click, but inlining product-specific detail that changes creates duplicate copies that drift apart. Deciding by stability keeps a single source of truth for the things that change.
URLs at the end of a sentence
Section titled “URLs at the end of a sentence”link-001 should GuidesAPI docs When a URL falls at the end of a sentence, rewrite the sentence or place the URL on a separate line to avoid confusion between the URL and the terminal period.
Examples
- ✓ “Open the dashboard at the following URL:” with
https://example.com/dashboardset on its own line - ✗ Open the dashboard at https://example.com/dashboard.
Rationale
A period right after a URL can look like part of the address, so recasting avoids the confusion.
Periods mistaken for URL characters
Section titled “Periods mistaken for URL characters”link-015 should GuidesAPI docs If a sentence-ending period could be mistaken for part of a URL, rewrite the sentence or set the URL off on its own line.
Examples
- ✓ “Your app is available at the following URL:” with
https://example.com/appset on its own line - ✗ Your app is available at https://example.com/app.
Rationale
A trailing period can look like part of the URL, so recasting or isolating the URL prevents a broken link.
Slashes in paths and URLs
Section titled “Slashes in paths and URLs”link-017 should GuidesAPI docs Use forward slashes in file paths and URLs; use backslashes for Windows paths.
Examples
- ✓ Open
config/settings.yaml. - ✗ Open
config\settings.yaml.
Rationale
Forward slashes are correct for URLs and POSIX paths; backslashes are only for Windows paths.
Straight quotes in source
Section titled “Straight quotes in source”link-018 should GuidesAPI docsMarketingBlog Do not use curly (smart) quotation marks or apostrophes anywhere in source, including body text. Use straight quotation marks and apostrophes. Curly quotes break many build systems and often fail without a clear error message.
Examples
- ✓ Don’t paste “smart” quotes into source files.
- ✗ Don’t paste “smart” quotes into source files.
Rationale
Curly quotes and apostrophes frequently break build tooling and produce errors that are hard to trace, while straight marks are safe across code and body text.
Consistent link styling
Section titled “Consistent link styling”link-016 should GuidesAPI docs Apply consistent visual styling to link text sitewide: distinguish link color from body text, underline links (and do not underline non-link text), and change visited link color.
Rationale
Consistent, distinct link styling tells readers what is clickable and what they have visited.