mkdocs-table-of-figures

This is a plugin that creates a figcaption with elements alt attribute or title and lists all figures in files into a table of figures to be integrated in Markdown pages for MkDocs.

Setup

Installing using pip:

pip install mkdocs-table-of-figures

Config

You need to activate the plugin in mkdocs.yml:

plugins:
  - table-of-figures:
      title_label: "Table of figures of the documentation" # Optional --> Default : Table of Figures
      figure_label: "Figure N°" # Optional --> Default : Figure
      description_label: "Description of the figures" # Optional --> Default : Description
      type_label: "Type of the figure" # Optional --> Default : Type
      section_label: "Section of the figure" # Optional --> Default : Section

      temp_dir: "folder_name" # Optional --> Default : temp_figures
      file: "file_name" # Optional --> Default : figures.md

      follow_nav_structure: true # Optional --> Default : true
      
      on_pair: true # Optional --> Default : false
      on_mermaid: true # Optional --> Default : false
      on_codeblock: true # Optional --> Default : false
      on_table: true # Optional --> Default : false

      show_type: true # Optional --> Default : false
      show_section: true # Optional --> Default : false

      image_type_name: Image Figure # Optional --> Default : Image
      pair_type_name: Pair of Images Figure # Optional --> Default : Pair
      mermaid_type_name: Mermaid Figure # Optional --> Default : Mermaid
      codeblock_type_name: Codeblock Figure # Optional --> Default : Codeblock
      table_type_name: Table Figure # Optional --> Default : Table

As you can see, every option is optional, but if you want to generate a table of figures in another language than English, you will need to set up label options.

• title_label - This is the title (heading 1) given to the page that will contain the table of figures.
• figure_label - This is the name given to every figure right before the auto-incremented number.
• description_label - This is the label given to the column containing the description of each figure (alt text).
• type_label - This is the label given to the cloumn containing the type of each figure (image, mermaid, codeblock, table).
• section_label - This is the label given to the cloumn containing the section of each figure (the location relative to headings and pages navigation).
• temp_dir - The temporary directory used to store the table of figures Markdown file before rendering to HTML. Only set this option if you already have a temp_figures folder in the root directory (same as mkdocs.yml), which you should not normally have.
• file - The name of the Markdown file containing the table of figures. Only set this option if you already have a figures.md file in the docs directory.
• follow_nav_structure - To order the figures in function of the navigation instead of alphabetical files order.
• on_pair - To enable pair of image support, to use when 2 comparative image need to be next to each others.
• on_mermaid - To enable mermaid diagrams support, need to use of md_in_html Markdown extension.
• on_codeblock - To enable code blocks support, need to use of md_in_html Markdown extension.
• on_table - To enable tables support, need to use of md_in_html Markdown extension.
• show_type - To enable the column showing info about the type of each figure (image, mermaid, codeblock, table).
• show_section - To enable the column showing info about the section of each figure (the location relative to headings and pages navigation)
• image_type_name - The label shown for each figure of type image
• pair_type_name - The label shown for each figure of type pair of image
• mermaid_type_name - The label shown for each figure of type mermaid
• codeblock_type_name - The label shown for each figure of type codeblock
• table_type_name - The label shown for each figure of type table

Usage

The plugin will only look for Markdown image composed of alt text. If you don't set any alt text for the Markdown image it will be ignored.

There is two way of correctly rendering image stored within the docs:

• Using url from base: this mean that you give the full path from the docs directory starting with / like this /path/to/image/from/docs/image.png
• With the help of md_in_html: there is a Markdown extension that you can set in mkdocs.yml that allow the plugin to place Markdown in HTML which allow this plugin to let MkDocs set relative link in src attribute properly during HTML rendering

Concerning external images nothing change.

You can set the md_in_html option like so :

markdown_extensions:
  - md_in_html

Using the command mkdocs build or mkdocs serve will trigger the plugin if it has been set correctly in the config file.

Support

Image like support

This plugin currently supports markdown images, pairs of images, mermaid diagrams, code blocks and table.

To make a pair of image you need to follow this structure:

| ![Version A](./image_a.png) | ![Version B](./image_a.png) |

There is no need to put any alt text for the second image. it will then generate a single description for the two image:

| ![Two versions of an image](./image_a.png) | ![](./image_a.png) |

To make it work space are needed between the images and the table separator |

Non-image like support

To make a mermaid diagram, code block or table detectable by this plugin, you need to give it a title at the line just below it like this:

    ``` php
    <?php
      $var = 42;
    ?>
    ```
    The title of the code block go here

    ``` mermaid
    sequenceDiagram
        participant Alice
        participant Bob
        Alice->>John: Hello John, how are you?
        loop Healthcheck
            John->>John: Fight against hypochondria
        end
        Note right of John: Rational thoughts <br/>prevail!
        John-->>Alice: Great!
        John->>Bob: How about you?
        Bob-->>John: Jolly good!
    ```
    The title of the mermaid diagram go here

    | Table   | Right | Center  | Left  |
    | ------- | ----: | :-----: | :---- |
    | A table |  With | Content | in it |
    The title of the table go here

It will not work if there is a line between the element and the title.

I highly recommend using mkdocs-material to use mermaid diagrams. For more info about mermaid diagrams, I invite you to check mkdocs-material and mermaid's official documentation.

I also recommend to add this stylesheet to prevent mermaid size from being reduced or code blocks from having code centered by mkdocs-material.

figure.figure-mermaid, figure.figure-codeblock {
    margin: 0 1em;
    width: calc(100% - 2em);
}

figure.figure-codeblock code {
    text-align: initial;
}

You can place the stylesheet in your mkdocs.yml at extra-css option

extra_css:
  - fix-mermaid-figure.css

Custom attributes

To use custom attributes on images, like this :

![Image alt](image.png){ width="300" }

it require glightbox and attr_list and md_in_html from mkdocs-material. More details on mkdocs-material documentation : https://squidfunk.github.io/mkdocs-material/reference/images/?h=image#image-alignment-left.

Note that align=left and align=right attributes will be overriden by figures style from mkdocs-material.

License

This project is under MIT license. See the license file for more details.

See Also

• GitLab Repo
• MkDocs Website
• MkDocs-Material Documentation
• Mermaid Documentation