Cross-references

In general, cross-references link to nonessential information that adds to the reader's understanding.

References to other documents

  • Give an explanation as to why you are referring the reader to this information.

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

  • 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.

  • If a link downloads a file, the link text needs to indicate this action as well as the file type.

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.

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 quotation marks.

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

  • For cross-references that are titles of published works such as books or movies, use italics and title caps but no quotation marks.

    Recommended: ...see The Chicago Manual of Style and its extremely helpful free online Q&A posts.

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

  • Configure the link to open in a new tab or window.
  • 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 icon and configure the icon with CSS to indicate that it opens in a new tab or window.

Recommended: For more information, see Links and Hypertext.