Skip to content

Referencing Figures And Tables

Referencing elements in markdown is pretty straight forward. Since this plugin adds a default id to all figures and tables created these ids can be used to reference the element. The following example shows how to reference a figure.

![Caption text](assets/demo.png)

See [Figure](#_figure-1) above for more details.

<figure id=_figure-1>
    <img src="assets/demo.png" alt="This uses the alt as caption" />
    <figcaption>Figure 1. Caption</figcaption>
</figure>
<p>See the <a href="#_figure-1">Figure</a> above for more details.</p>

Warning

Although a default id is added to each figure/table it is not recommended use it as a reference. The reason is that the order of the figures/tables might change. This will result in the wrong figure/table being referenced. Instead it is recommended to assign a custom id to the figure/table.

Automatic Link Text Generation

Often one would like the link text to look something like Figure 1 or Table 1. Sure this can be done manually, but it is tedious and error prone. This plugin can automatically generate the link text for you. This done by referencing the figure/table id and not specifying a link text.

![Caption text](assets/demo.png)

See [](#_figure-1) above for more details.

<figure id=_figure-1>
    <img src="assets/demo.png" alt="This uses the alt as caption" />
    <figcaption>Figure 1. Caption</figcaption>
</figure>
<p>See <a href="#_figure-1">Figure 1</a> above for more details.</p>

Note

The link text can be customized by using the reference_text option in the configuration. See the config chapter for more details.

Cross Page referencing

The automatic link text generation also works across pages. The mechanism is the same as for local references. If no link text is specified the plugin tries to replace it with the autogenerated link text.

page_a.md

![Caption text](assets/demo.png)

page_b.md

See [](page_a.md#_figure-1) for more details.

page_a.html

<figure id=_figure-1>
    <img src="assets/demo.png" alt="This uses the alt as caption" />
    <figcaption>Figure 1. Caption</figcaption>
</figure>

page_b.html

<p>See <a href="page_a.html#_figure-1">A/Figure 1</a> for more details.</p>

Note

The config parameter cross_reference_text can be used to customize the link text for cross references. The default is {page_title}/{local_ref}