2026-10-192026-10-19

Config

Default

Back to: References
Back to: Caption Main Page
Back to: Image Caption

Config

• The plugin can be configured in the mkdocs.yml file.
• The default configuration is as follows:

---

plugins:
  - caption:
    additional_identifier: []  # (1)!
    cross_reference_text: '{page_title}/{local_ref}'
    table: # (2)!
      enable: true
      start_index: 1
      increment_index: 1
      position: bottom
      default_id: '_table-{index}'
      reference_text: 'Table {index}'
      caption_prefix: 'Table {index}:'
      markdown_identifier: 'Table:'
      allow_indented_caption: True
    figure: # (3)!
      enable: true
      start_index: 1
      increment_index: 1
      position: bottom
      default_id: '_figure-{index}'
      reference_text: 'Figure {index}'
      caption_prefix: 'Figure {index}:'
      markdown_identifier: 'Figure:'
      allow_indented_caption: True
      ignore_alt: False
      ignore_classes: ["twemoji"]
      ignore_hash: False
    custom: # (4)!
      enable: true
      start_index: 1
      increment_index: 1
      position: bottom
      default_id: '_{identifier}-{index}'
      reference_text: '{Identifier} {index}'
      caption_prefix: '{Identifier} {index}:'
      markdown_identifier: '{Identifier}:'
      allow_indented_caption: True

1. list of additional identifiers (e.g. [List, Example]. These identifiers will be treated as custom captions. Note that each identifier has its own counter.)
2. Configuration that applies for the table captioning.
3. Configuration that applies for the figure/image captioning.
4. Configuration that applies for the custom element captioning. Note that this configuration applies for all elements that are specified in the additional_identifier list.

The {index} placeholders are replaced with the current index. The {identifier} placeholder is replaced with the lower case identifier and the {Identifier} is replaced with the capitalized identifier.

• The configuration in the mkdocs.yml file is applied to all custom identifiers.
• It is not possible to customize the figure element for a specific identifier only.

• The configuration can be split in three parts: table, figure and custom.

• Each part has the same configuration options that apply for the respective element.

• The following table lists all available options.

Option	Description
enable	Enable/disable the captioning/plugin for the specified identifier
start_index	The index to start with
increment_index	The increment for the index
position	The position of the caption (top, bottom) relative to the target element
default_id	The default id assigned to the resulting HTML element
reference_text	The text used for references to this element. Note, this only will be applied if the anchor does not specify its own link text
caption_prefix	The prefix put before of the caption text
markdown_identifier	The identifier that this plugin will search for in the markdown. (Note that every match of this identifier will be treated as a caption element. A false match will most likely result in an error)
allow_indented_caption	Flag if caption elements should also be parsed within indented blocks. By default this is enabled.
ignore_alt	Flag if the alt attribute should be ignored. This will disable the feature that
uses the alt text as a caption. (Only available for figures)
ignore_classes	List of classes ignored when adding the captions. (Only available for figures)
ignore_hash	Flag is there is not special parsing of hashes in the image url. This disables the support for packing images into the same figure (e.g light and dark mode)

Overwriting the default configuration

Overwriting the "default config"

• It is also possible to overwrite the default configuration (mkdocs.yml) for a specific page.

• This can be done by adding a caption section to the page header.

  ---
  caption:
    table:
      start_index: 4
  ---
  # Page Title
  ...
  

---

Highlighting Changes

When Critic is enabled, Critic Markup can be used, which adds the ability to highlight suggested changes, as well as add inline comments to a document:

Text with suggested changes

Text can be {--deleted--} and replacement text {++added++}. This can also be combined into {~~one~>a single~~} operation. {==Highlighting==} is also possible {>>and comments can be added inline<<}.

{==

Formatting can also be applied to blocks by putting the opening and closing tags on separate lines and adding new lines between the tags and the content.

==}

Text can be deleted and replacement text added. This can also be combined into onea single operation. Highlighting is also possible and comments can be added inline.

Formatting can also be applied to blocks by putting the opening and closing tags on separate lines and adding new lines between the tags and the content.