Cross References

A link to another location within the current AsciiDoc document or in another AsciiDoc document is called a cross reference (also referred to as an xref). To create a cross reference, you first need to define the location where the reference will point (i.e., the anchor). Then, you need to use one of the forms of the inline xref macro to create a reference to that location. From there, you can customize the text of the reference in various ways.

Automatic anchors

It’s important to understand that many anchors are already defined for you. Using default settings, the AsciiDoc processor automatically creates an anchor for every section and discrete heading. It does so by generating an ID for that section (or discrete heading) and registering that ID in the references catalog. You can then use that ID as the target of a cross reference.

For example, considering the following section.

= Section Title

The AsciiDoc processor automatically assigns the ID _section_title to this section, which you can then use as the target of an xref to create a reference to this section. You can also customize how this ID is generated. Refer to Autogenerate Section IDs for more information about how an AsciiDoc processor generates these IDs.

If you’re referring to a content element other than a section, you’ll need to define an anchor on that element explicitly.

Internal cross references

In AsciiDoc, the shorthand xref is used to create a cross reference to an element (e.g., section, block, list item, etc.) that has an ID within the same document. The shorthand xref is processed by the macros substitution.

If the cross reference specifies both an ID and text, the text is formatted and used as the link text. If the cross reference only specifies the ID, the reftext of the target element (typically the formatted title) is automatically used as the link text. If the element does not define reftext, a stylized form of the ID is used instead. Whether the ID is assigned explicitly on the referenced element or auto-generated does not affect how this mechanism works.

Currently, an AsciiDoc processor can resolve a cross reference to the following elements:

  • Section (ID or block anchor)

  • Block (ID or block anchor)

  • Block macro (ID)

  • Inline anchor anywhere in a paragraph

  • Inline anchor at the start of a list item or table cell

  • Bibliography anchor in a bibliography list

Note that the processor cannot resolve the ID assigned to a span of formatted text. If the cross reference cannot be resolved, and verbose mode is enabled, the AsciiDoc processor issues a warning about a possible invalid reference. In this case, the output document will reference the target blindly, so it’s possible it will still function.

You create a cross reference by enclosing the ID of the target block or section (or the path of another document with an optional anchor) in double angled brackets.

Example 1. Cross reference using the ID of the target section
The section <<anchors>> describes how automatic anchors work.

The result of Example 1 is displayed below.

The section Automatic anchors describes how automatic anchors work.

Explicit link text

Converters usually use the reftext of the target as the default text of the link. When the document is parsed, attribute references in the reftext are substituted immediately. When the reftext is displayed, additional reftext substitutions are applied to the text (specialchars, quotes, and replacements).

You can override the reftext of the target by specifying alternative text at the location of the cross reference. After the ID, add a comma and then enter the custom text you want the cross reference to display.

Example 2. Cross reference with custom xreflabel text
Learn how to <<link-macro-attributes,use attributes within the link macro>>.

You can also use the inline xref macro as an alternative to the xref shorthand.

Example 3. Inline xref macro
Learn how to xref:link-macro-attributes[use attributes within the link macro].

However, it’s best to reserve the use of the xref macro for creating interdocument cross references.

Natural cross reference

You can also create a reference to a block or section using its title rather than its ID. This type of reference is referred to as a natural cross reference. The title must contain at least one space character or contain at least one uppercase letter.

Example 4. Cross reference using a section’s title
Refer to <<Internal Cross References>>.

As a rule of thumb, the natural cross reference should only be used for rapid development or short-lived content. As the content matures, you should switch to using IDs for referencing, ideally IDs which are declared explicitly. By doing so, it ensures your references have maximum stability and are shielded against title revisions.