In general, cross-references link to nonessential information that adds to the reader's understanding.
When possible, provide help in context, rather than linking elsewhere. For example, when the information is short, such as defining a term inline, explaining a concept, or providing a couple of steps, consider including the information in your document instead of providing a link.
For more information about internal and external references, see the following:
References to other documents
Follow these guidelines when linking to other documents:
- Use see to refer to links and cross-references. For more information, see see.
Use meaningful link text.
Recommended: For more information about how to code right away, see 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.
Recommended:
<a href="/style/accessibility" target="_blank">Accessible content (opens in a new tab)</a>
Not recommended:
<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.
Word cross-references
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.
Format 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.
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.
For example, use /compute/docs/instances as the target for a link within Google
Cloud documentation, not /instances or
https://cloud.google.com/compute/docs/instances.
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: For more information, see the Word cross-references section of this document.
Links to sections on another page
When you're linking to a section on another page, use the same wording and formatting as a regular cross-reference.
If the title of the section that you're linking to is identical to a title on the source page, add context to the cross-reference.
Recommended: For more information, see Download the sample data.
Recommended: For more information, see Install libraries in "Building new audiences based on existing customer lifetime value."
For more information about wording cross-references and link text, see Link text.
Links to pages on a different server
If the server that you're linking to supports HTTPS, start the URL with https. If
the server doesn't support HTTPS, start the URL with http.
Don't use an external link icon to indicate that the link goes to a different domain or server. If you think it's important to inform the reader that they're leaving a Google domain, mention it in the text and don't rely on an icon.
Recommended:
For more information, see OS-level virtualization.
Sometimes OK:
For more information, see the Wikipedia page about OS-level virtualization.
Not recommended:
For more information, see OS-level virtualization.