Asciidoctor User Manual

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 an 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 Auto-generated 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. Read on to learn how.

An anchor (aka ID) can be defined almost anywhere in the document, including on section title, on a discrete heading, on a paragraph, on an image, on a delimited block, on an inline phrase, and so forth. The anchor is declared by enclosing a valid XML Name in double square brackets (e.g., [[idname]]) or using the shorthand ID syntax (e.g., [#idname]) at the start of an attribute list.

The double square bracket form requires the ID to start with a letter, an underscore, or a colon, ensuring the ID is portable. According to the XML Name rules, a portable ID may not begin with a number, even though a number is allowed elsewhere in the name. The shorthand form in an attribute list does not impose this restriction.

If you want to reference a block element, all you need to do is assign an ID to that block. You can enclose the ID in double square brackets:

or use the shorthand ID syntax:

You can also define an anchor anywhere in content that receives normal substitutions (specifically the macro substitution). You can enclose the ID in double square brackets:

or using the shorthand ID syntax.

In addition to being able to define anchors on sections and blocks, anchors can be defined inline where ever you can type normal text (anchors are a macro substitution). The anchors in the text get replaced with invisible anchor points in the output.

For example, you would not put an anchor in front of a list item:

Instead, you would put it at the very start of the text of the list item:

Here’s how you can define the ID for a section using an inline anchor:

To add additional anchors to a section, place them in front of the title.

Remember that inline anchors are discovered where ever the macro substitution is applied (e.g., paragraph text). If text content doesn’t belong somewhere, neither does an inline anchor point.

It’s possible to customize the text that will be used in the cross reference link (called xreflabel). If not defined, Asciidoctor does it best to find suitable text (the solution differs from case to case). In case of an image, the image caption will be used. In case of a section header, the text of the section’s title will be used.

To define the xreflabel, add it in the anchor definition right after the ID (separated by a comma).

Instead of the bracket form, you can use the macro anchor to achieve the same goal.

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.

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.

Asciidoctor provides limited support for validating internal cross references. Validation occurs when a cross reference is first visited. Since there are still some references aren’t stored in the parse tree (such as an anchor in the middle of a paragraph), which can lead to false positives, these validations are hidden behind a flag.

You can enable validation of cross references from the CLI by passing the -v and from the API by setting the $VERBOSE variable to true. This puts the processor in pedantic mode. In this mode, the parser will immediately validate cross references, issuing a warning message if the reference is not valid.

Consider the following example:

If you run Asciidoctor in verbose/pedantic mode on this document, it will send the following warning message to the logger.

Asciidoctor only validates references within the same document (after includes are resolved).

Starting in Asciidoctor 1.5.6, when you use one of the native converters (HTML, PDF, and EPUB3), you can customize the style of the automatic cross reference text using the xrefstyle document attribute. This customization brings the cross reference text formatting from the DocBook toolchain to the native Asciidoctor converters.

By default, the cross reference text matches the title of the referenced element. For example, if you’re linking to a section titled “Installation”, the text of the cross reference link appears as:

If the reftext attribute is specified on the referenced element, that value is preferred over its title. For example, let’s assume the section from the previous example was written as:

In this case, the text of the cross reference link appears as:

Attribute references are substituted in the reftext during parsing and reftext substitutions (specialchars, quotes, and replacements) are applied to the value when it’s used during conversion.

If the reftext is not specified, the text of the cross reference is automatically generated. By default, this text is the title of the reference. There are three built-in styles you can choose from to customize the generated text of a cross reference, as controlled by the xrefstyle document attribute.

This formatting only applies to references that have both a title and number (or explicit caption), but no explicit reftext. If the reference is a chapter or an appendix, the title is displayed in italics instead of quotes (even when the xrefstyle is basic).

Let’s assume you want to reference a section titled “Installation” that has the number 2.3. The full style is displayed as:

The short style is displayed as:

The basic style is displayed as:

The full and short styles only apply for references that have a caption. Specifically, the corresponding -caption attribute must be set for the target’s block type (e.g., listing-caption for listing blocks, example-caption for example blocks, table-caption for tables, etc.). Otherwise, the *basic style is used.

You can use document attributes to customize the signifier that is placed in front of the reference’s number. This reference signifier indicates the reference’s type (e.g., Chapter or Section).

(The signifier attribute for a part cross reference will be introduced once numeration is supported for parts).

For example, to customize the word “Section”, define the section-refsig attribute in the document header:

The full xrefstyle would then be displayed as:

The short xrefstyle would be displayed as:

If you unset the attribute, the signifier is dropped from the cross reference text. For example:

In this case, the full xrefstyle will display only the number and title:

The short xrefstyle will fall back to the number only:

The basic xrefstyle is unaffected by the value of the signifier.

Only the aforementioned styles are provided out of the box. Support for a custom formatting string is planned. Refer to #2212 for details. Until then, you can implement custom formatting in a custom converter or overridding the xreftext method on the node.

The inline xref macro can also link to IDs in other AsciiDoc documents. This eliminates the need to use direct links between documents that are coupled to a particular converter (e.g., HTML links). It also captures the intent of the author to establish a reference to a section in another document.

Here’s how a cross reference is normally defined in Asciidoctor:

This cross reference creates a link to the section with the ID images.

Let’s assume the cross reference is defined in the document document-a.adoc. If the target section is in a separate document, document-b.adoc, the author may be tempted to write:

However, this link is coupled to HTML output. What’s worse, if document-b.adoc is included in the same document as document-a.adoc, the link will refer to a document that doesn’t even exist!

These problems can be alleviated by using an inter-document xref:

The ID of the target is now placed behind a hash symbol (#). Preceding the hash is the name of the reference document (the file extension is optional). We’ve also added a label since Asciidoctor cannot (yet) resolve the section title in a separate document.

When Asciidoctor generates the link for this cross reference, it first checks to see if document-b.adoc is included in the same document as document-a.doc. If not, it will generate a link to document-b.html, intelligently substituting the original file extension with the file extension of the output file.

If document-b.adoc is included in the same document as document-a.doc, then the document will be dropped in the link target and look like the output of a normal cross reference:

Now you can create inter-document cross references without the headache.