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.](label:text_without_supplement)
renders as
Reference links
Reference links are supported:
[A reference to the text][1]
[1]: ref:a_piece_of_text
renders as
Autolinks
Autolinks are also supported, but only work if the reference has a supplement:
<ref:a_piece_of_text>
<ref:my-heading>
renders as
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
<center>
The rest describes its contents, which are rendered as
**markdown** _in_ `the` final document.
</center>
```
which renders as
markdown in the final document.
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
| Column 1 | Column 2 |
|---|---|
| Value1 | Value2 |
and is referred to as Table 1