MkDocs Caption


Package
Meta
CI

Enhance your MkDocs documentation with easy figure, table captioning and numbering.

Features

Table and Figure captioning and numbering
Automatic link text generation for references
Highly configurable
Extensible to support captions for all Element types

Background

I developed mkdocs-caption when I switched from Antora (AsciiDoc) to MkDocs and was missing a native and comprehensive figure and table caption system.

mkdocs-caption uses many ideas and markdown syntax from flywire/caption, which itself is a fork of yafg - yet another figure generator plugin for Python's Markdown. Although initially developed separately and not sharing any code, I was made aware of flywire/caption, and it's worth crediting it here.

Documentation

For full documentation, visit https://tobiasah.github.io/mkdocs-caption/.

Installation

pip install mkdocs-caption

Quick Usage

In mkdocs.yml:

...
plugins:
- caption

Inside the Markdown, the following will now be converted into a figure/table with caption and numbering.

![figure caption](img.jpg)

Table: table caption

| heading 1| heading 2 | 
| - | - | 
| content 1 | content 2 |
| content 3 | content 4 |

<p>
  <figure id=_figure-1>
    <img src="img.jpg" />
    <figcaption>Figure 1. figure caption</figcaption>
  </figure>
</p>
<p>
<table id="_table_1">
  <thead>
    <tr>
      <th>heading 1</th>
      <th>heading 2</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>content 1</td>
      <td>content 2</td>
    </tr>
    <tr>
      <td>content 3</td>
      <td>content 4</td>
    </tr>
  </tbody>
  <caption>Table 1: table caption</caption>
</table>