Image Caption¶
By default, MkDocs does not wrap images in a <figure> tag. A markdown image
tag simply translates into an HTML <img> tag. This plugin enables the user
to wrap images in an HTML <figure> tag and specify a caption for the image.
Adding a caption¶
There is more than one way to add a caption to an image. This page explains in all options in detail.
Important
If none of the described options apply, the image remains untouched. Meaning
that the image is not wrapped in a <figure> tag and no caption is added.
Using the alt attribute as caption¶
The easiest way to add a caption to an image is to use define an alt text for the image. In markdown this is done by adding a text in the square brackets:
<figure id=_figure-1>
<img src="assets/demo.png" alt="This uses the alt as caption" />
<figcaption>Figure 1. This uses the alt as caption</figcaption>
</figure>
Note
By default, every figure is assigned a default id (_figure-x). This id
can be used to reference the figure. It is however recommended to
assign a custom id to the image directly, or to the figure tag (see the
customization section below). This will ensure that the
correct image is referenced even if the order of the images changes.
Using the title attribute as caption¶
MkDocs by default is able to assign a title to an image. The Caption plugin
is able to use this title as a caption for the figure.
A title can be assigned to an image by adding a quoted text right after the image path:
<figure id=_figure-1>
<img src="assets/demo.png"/>
<figcaption>Figure 1. This uses the title as caption</figcaption>
</figure>
Note
By default, every figure is assigned a default id (_figure-x). This id
can be used to reference the figure. It is however recommended to
assign a custom id to the image directly, or to the figure tag (see the
customization section below). This will ensure that the
correct image is referenced even if the order of the images changes.
Note
If both the alt and title attribute are present, the title attribute
is used as caption. This allows the user to define both a caption and an
alt text for the image.
Using the Figure identifier as caption¶
The most flexible way to add a caption to an image is to use the Figure
identifier (by default Figure:) to define the caption.
This identifier is unique to the Caption plugin and is also used for the
table and custom captioning. The identifier must be placed right before the
image and has the following syntax:
Figure: This uses the identifier as caption
<figure id=_figure-1>
<img src="assets/demo.png"/>
<figcaption>Figure 1. This uses the identifier as caption</figcaption>
</figure>
Danger
The caption can stretch over multiple lines. However it must end with a blank line before the image. Otherwise the image will be interpreted as part of the caption.
Note
By default, every figure is assigned a default id (_figure-x). This id
can be used to reference the figure. It is however recommended to
assign a custom id to the image directly, or to the figure tag (see the
customization section below). This will ensure that the
correct image is referenced even if the order of the images changes.
Note
This syntax is custom to the Caption plugin and is not supported by
MkDocs natively. However, even if the plugin is not enabled (e.g. in the
Github/text editor preview) the image will still be rendered correctly, and
the caption will be displayed as normal text above the image. This helps
the readability outside MkDocs.
Tip
The identifier can be customized in the mkdocs.yml configuration file
through the caption_prefix. See the Config chapter for more details.
Customizing the Figure element¶
The plugin allows customizing the figure element. One way is through the
mkdocs.yml configuration file (e.g. position of the caption relative to the
image). The other way is to add attributes to the caption.
Important
Only when using the Figure: identifier,
attributes can be added directly to figure element. If the alt or title
attribute is used, attributes can only be added to the img element directly.
Attributes are added to the figure element by adding a curly bracket after the
figure identifier and specifying the attributes inside the curly brackets. This
is not unique to the Caption plugin, but is a general feature of the extended
Markdown syntax used by MkDocs.
Tip
The class attribute can be assign with .class_name
Tip
The id attribute can be assign with #id_name and overrides the default id.
Figure: Caption Text {.my_class #my_id any_attribute="value"}
<figure id="my_id" class="my_class" any_attribute="value">
<img src="assets/demo.png"/>
<figcaption>Figure 1. Caption Text</figcaption>
</figure>