Cross-references

In general, cross-references link to nonessential information that adds to the reader's understanding. For more information about internal and external references, see Link text and Capitalization in titles and headings.

References to other documents

  • Use meaningful link text.

    Not recommended: See this blog post.

    Not recommended: Click here.

    Recommended: To begin coding right away, read Building your first app.

  • If the link text doesn’t clearly indicate why you're referring the reader to this information, then give an explanation. Make the explanation specific, but don't repeat the link text.

    Recommended: For more information about authentication and authorization, see Using OAuth 2.0 to access Google APIs.

  • If a link downloads a file, then make that clear in the link text, and mention the file type.

    Recommended: For more information, download the security features PDF.

  • To avoid link fatigue, don't provide duplicate links to the same document within a given page. It's OK to add a secondary link if you're linking to a particular section of another page, if the page you're linking from is long, or if there are multiple entry points to the document that you're linking from. For example, if a how-to page has a troubleshooting section, you can add a link in both sections of that page.

Cross-references within generated reference documents

When linking from one reference topic to another in generated reference documents, use the reference generator's standard linking syntax rather than hard-coding links within the reference, so that the links will change appropriately when the reference docs change.

Wording cross-references

When a cross-reference includes information that describes what the cross-reference links to, use about instead of on.

Not recommended: For more information on indexes, see Managing indexes.

Recommended: For more information about indexes, see Managing indexes.

For more information about wording cross-references and link text, see Link text.

Formatting cross-references

  • When a cross-reference is a link, don't put the link text in quotation marks.

    Recommended: For more information, see Meet Android Studio.

    Recommended: Learn about what's new in Android Wear 2.0.

  • In the rare case when a cross-reference isn't a link, use italics or quotation marks as appropriate.

    • For an unlinked reference to a document section, short work, or part of a series—such as an episode in a web series—use quotation marks.

      Recommended: For more information, see "Describing system versions" in the following section.

    • For an unlinked reference to the title of a full-length work—such as a book, movie, or web series—use italics.

      Recommended: ...see The Chicago Manual of Style.

URLs in links to pages on the same server

When you're linking to another page on the same server, use a site-root-relative URL starting with /, even if you're linking to a page in the same directory as the page you're linking from.

Note: There are many valid linking styles; this guideline isn't a general statement about best practices for linking in all contexts; it's just our house style.

Links to sections in the same page

When you're linking to another section in the same page, let the reader know that the link takes you to a different section of the same page. Use a standard phrase to clue readers in if you use an in-page link.

Recommended: In this document, see URLs in links to pages on the same server.

Links to pages on a different server

  • Don't force links to open in a new tab or window. Let the reader decide how to open links. If you think a link needs to open in a new tab or window, let the reader know that the link is opening differently than expected. For example, if the following link opens in a new tab, the link text should let them know: Accessible content (opens in a new tab).
  • If the server you're linking to supports HTTPS, start the URL with https. If the server doesn't support HTTPS, start the URL with http.
  • Use an external link icon to indicate that the link goes to a different domain or server. For example,a link from cloud.google.com to support.google.com is an internal link, whereas a link from cloud.google.com to kubernetes.io is an external link.

Recommended: For more information, see Links and Hypertext.