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="https://github.com/tobiasah/mkdocs-caption/raw/main/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>

License

mkdocs-caption is distributed under the terms of the MIT license.