Cross References

It’s important to understand that many anchors are already defined for you. Using default settings, Asciidoctor 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.

Asciidoctor 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 Autogenerated Section IDs for more information about how Asciidoctor 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.

In Asciidoctor, the inline xref macro is used to create cross references (also called in-text or page citations) to content elements (sections, blocks, or phrases) that have an ID (regardless of whether that ID is explicit or auto-generated).

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.

The result of Example 1 is displayed below.

The section Automatic anchors describes how automatic anchors work.

You can also link to a block or section using the title by referencing its title, referred to as a natural cross reference. The title must contain at least one space character or contain at least one uppercase letter. (If you are using Ruby < 2.4, that uppercase letter is restricted to the basic Latin charset).

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.

You can also use the inline xref macro as an alternative to the double angled bracket form.