In general, cross-references link to nonessential information that adds to the reader's understanding. For more information about internal and external references, see the following:
References to other documents
Follow these guidelines when linking to other documents:
Use meaningful link text.
Recommended: To begin coding right away, read Building your first app.
Not recommended: See this blog post.
Not recommended: Click here.
Don't force links to open in a new tab or window. Let the reader decide how to open links. In the rare situation that a link needs to open in a new tab or window, let the reader know that the link opens differently than expected.
<a href="/style/accessibility" target="_blank">Accessible content (opens in a new tab)</a>
<a href="/style/accessibility" target="_blank">Accessible content</a>
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 that 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 change appropriately when the reference documents change.
When a cross-reference includes information that describes what the cross-reference links to, use about instead of on.
Recommended: For more information about indexes, see Managing indexes.
Not recommended: For more information on indexes, see Managing indexes.
For more information about wording cross-references and link text, see Link text.
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.
Not recommended: For more information, see "Meet Android Studio".
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 that 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 on the same page
When you're linking to another section on 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 on-page link.
Recommended: In this document, see URLs in links to pages on the same server.
Links to pages on a different server
If the server that you're linking to supports HTTPS, start the URL with
the server doesn't support HTTPS, start the URL with
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.