The mdbook-xref preprocessor

This preprocessor allow you to create cross-referenceable IDs by creating new link items that use the label protocol. Additionally, it lets you set the supplement (the text substituted at the place of reference) for these links, which is used unless the reference specifies its text explicitly.

The created labels can then be referred to using links with the ref protocol.

The benefits of this approach over the usual linking approach using fixed anchors and relative links is that labels are moveable, as a reference to a label is valid as long as it exists, regardless its location in the book. Additionally, broken links/references become apparent much more quickly: the preprocessor will produce an error if the label specified in a ref is undefined.

Quick Start

To get started, install the preprocessor:

cargo install mdbook-xref

and add it to your book.toml:

[book]

[preprocessor.xref] # This is all you need to do

and start creating labels and references.

That’s all there is to it! To find out how to actually use the preprocessor in more detail, see creating links.

If you have other mdbook preprocessors that might produce labels or refs, make sure that they are called before this preprocessor by adding before = [ "xref" ] to its configuration.

Creating cross-referenceable labels

Any link (inline, reference, autolink) with the label protocol will be interpreted as a cross-referenceable ID on the page where that label is created. That the essence of this preprocessor: it associate an ID with a specific page and lets you easily reference that ID in other places.

For instance, the preprocessor lets you create a piece of referenceable text (with support for inline markdown) as follows:

[a piece of referenceable text](label:a_piece_of_text "an optional supplement")

[a piece of **referenceable** _text_ without supplement, but nice markdown](label:text_without_supplement)

which is rendered like this:

a piece of referenceable text

a piece of referenceable text without supplement, but nice markdown

Cross-referencing other elements

Non-text elements can also be cross-referenced as follows:

##### A referenceable heading { #heading }
[](label:heading "the heading's supplement")

Labels without any text are not rendered, but cross-references to heading will create a link to the element with ID of the label, which in this case is heading (using mdBooks built-in heading ID support).

It is rendered like this (note that the labelled data is not explicitly visible):

A referenceable heading

In general, you should not create cross-referenceable items like this manually. Instead, you should let other preprocessors generate them for you.

Referring to cross-referefences

A cross reference can be referred to by any links with the ref protocol followed by a label defined in some label link.

Normal inline links

Normal inline links work as expected

[A reference to the text.](ref:text_without_supplement)

renders as

A reference to the text.

Reference links

Reference links are supported:

[A reference to the text][1]

[1]: ref:a_piece_of_text

renders as

A reference to the text

Autolinks

Autolinks are also supported, but only work if the reference has a supplement:

<ref:a_piece_of_text>

<ref:my-heading>

renders as

an optional supplement

the heading’s supplement

Cross-references work across pages

Cross-references, created as specified in the section on creating references also work perfectly fine across pages. For example, we can link to the heading’s supplement and an optional supplement.

The mdbook-figure preprocessor

This preprocessor allows you to define figures with a label, an optional type, a description, and contents.

Quick Start

To get started, install the preprocessor:

cargo install mdbook-figure

and add it to your book.toml:

[book]

[preprocessor.figure]
# If you're also using `mdbook-xref`, you must use the correct ordering:
before = [ "xref" ]

Defining figures

Defining figures is done as follows:

```figure a-label Optional Type
The first line is the description of the figure, which **can** _contain_ `markdown`.
<center>
The rest describes its contents, which are rendered as

**markdown** _in_ `the` final document.
</center>
```

which renders as

The figures are numbered by type and order in the book.

These figures can be referred to by their label using the mdbook-xref preprocessor. In this case, we can refer to ref:a-label, or Table 1.

Autodetection

If the type of the figure is not specified, it defaults to “Figure”. However, the type is automatically inferred for some content, so long as that content immediately follows the description.

Currently, only “Table” is supported:

```figure a-table
a very fancy table
| Column 1 | Column 2 |
| :------- | :------- |
| Value1   | Value2   |
```

which renders as

and is referred to as Table 1

Styling

With the html renderer, figures are turned into div elements with the figure class. Additionally, the figure caption is inserted as a p element with the figure-caption class.

The mdbook-abbr2 preprocessor

This preprocessor, in combination with the mdbook-xref preprocessor, provides simple abbreviation support for your mdBook.

Abbreviations are defined in a CSV file (whose path is configured using the preprocessor.abbr2.path configuration key in your book.toml) in the following format:

<Abbreviation>, <Description>[, <Optional hover text>]
# For example
CSV, Comma Separated Value
# And with custom hover text
CAB, Complicated Abbreviation with a very long description that's unsuitable for hover text, Complicated Abbreviation

Referring to abbreviations can then be done by using autolinks with the abbr scheme:

When writing a <abbr:CSV> file, make sure to escape double quotes with double quotes, and
<abbr:CAB> to explain other concepts.

renders as:

When writing a CSV file, make sure to escape double quotes with double quotes, and CAB to explain other concepts.

Abbreviations expand to links in the abbreviations page, which is appended to the end of the book, with a separator. To disable the chapter separator, set the preprocessor.abbr2.separator configuration key to false.

Getting started

To get started, install the preprocessors:

cargo install mdbook-xref mdbook-abbr2

and add the required configuration to your book.toml:

[preprocessor.xref]

[preprocessor.abbr2]
before = ["xref"]
path = "abbreviations.csv"

Abbreviations