Internal Xrefs

Internal xrefs are references to other elements within the same page. You can reference sections, blocks, or inline elements. These xrefs only require specifying the anchor (aka ID).

Reference a section in the same page

Section title IDs are automatically generated when AsciiDoc pages are processed, so you can use them as links by referencing the section’s title. However, the title must begin with an uppercase letter (in basic Latin) without any leading formatting marks.

To link to the beginning of a section in the same page, use the in-page cross reference which is designated by a set of double angled brackets (<< >>).

Example 1. Link to section title in the same page
This is an in-page cross reference: <<Reference a section in the same page>>. (1)

This is an in-page cross reference:
<<reference-a-section-in-the-same-page,Check it out>>! (2)
1 In-page xref to a section using the section’s title.
2 In-page xref to a section using the section’s implicit ID.

Reference a block or inline element in the same page

To link to a block or inline element in the same page, you must define an ID at that location.

Example 2. Create an ID
[#playbook] (1)
Here's an example of a playbook.

This is an [#name-me]#inline ID#. (2)
1 An ID can be placed on a paragraph (i.e., block).
2 An ID can be placed inline.

There are some exceptions, see the defining an anchor section in the Asciidoctor manual for more use cases.

To link to that ID, use the same in-page xref syntax you use for section headings.

Example 3. Link to an ID
We'll walk through a <<playbook,detailed example>> of a playbook in this tutorial.
Asciidoctor resources