Cross Reference Text and Styles

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.

The generated text of a cross reference is controlled by the xrefstyle. It will also vary for different element types (section, figure, etc). Let’s consider the following document to learn how the xrefstyle value affects the generated text of a cross reference.

There are three built-in styles supported by the xrefstyle document attribute that you can choose from to customize the generated text of a cross reference.

The xrefstyle attribute can also be specified directly on the xref macro to override the xrefstyle value for a single reference (e.g., xref:installation[xrefstyle=short]). The element attribute supports the same three styles.

The xrefstyle 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 <context>-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 overriding the xreftext method on the node.