A MkDocs plugin listing all figures to create a table of figures page
Project description
mkdocs-table-of-figures
This is a plugin that creates a figcaption
with image alt
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
temp_dir: "folder_name" # Optional --> Default : temp_figures
file: "file_name" # Optional --> Default : figures.md
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.
Set at least one annex to use this plugin. If you don't have any annex, don't add this plugin to the MkDocs
plugins list in the config file mkdocs.yml
.
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).temp_dir
- The temporary directory used to store the table of figuresMarkdown
file before rendering to HTML. Only set this option if you already have atemp_figures
folder in the root directory (same asmkdocs.yml
), which you should not normally have.file
- The name of theMarkdown
file containing the table of figures. Only set this option if you already have afigures.md
file in thedocs
directory.
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 aMarkdown
extension that you can set inmkdocs.yml
that allow the plugin to placeMarkdown
inHTML
which allow this plugin to letMkDocs
set relative link in src attribute properly duringHTML
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
This plugin currently supports markdown images and mermaid
diagrams.
To make a mermaid
diagram detectable by this plugin, you need to give it a title just below the end of the code block like this:
``` 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
It will not work if there is a line between the diagram 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.
License
This project is under MIT license. See the license
file for more details.
See Also
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mkdocs-table-of-figures-0.1.5.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7948c240796726bc9c83d43b235ae52f1e2d17fad1a44e4dd1c0325e05b9258b |
|
MD5 | b168e9282154421e5e9277099811d784 |
|
BLAKE2b-256 | f2cf0cbbb43c55bf2008923a56dd1c309969a83ded2fb8c5555f0fcf306f0c5f |
Hashes for mkdocs_table_of_figures-0.1.5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2e3756085092cc59b9b3c6384bd3b6cecb6b44c9673c3b667dc29e4fea37a74e |
|
MD5 | ddeae32fc35ccbbce8c76ba5b15e1b59 |
|
BLAKE2b-256 | 91050aef366090a541901231840a47ae003faf684d7d14e3ad698097fdd31e9b |