# 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`:
``` yaml
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 :
``` yaml
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:
``` markdown
|  |  |
```
There is no need to put any alt text for the second image. it will then generate a single description for the two image:
``` markdown
|  |  |
```
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:
``` markdown
``` php
<?php
$var = 42;
?>
```
The title of the code block go here
```
``` markdown
``` 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
```
``` markdown
| 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.
``` css
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
``` yml
extra_css:
- fix-mermaid-figure.css
```
### Custom attributes
To use custom attributes on images, like this :
``` markdown
{ 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](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](http://www.gitlab.org/cfpt-mkdocs-plugins/mkdocs-table-of-figures/)
- [MkDocs Website](http://www.mkdocs.org/)
- [MkDocs-Material Documentation](https://squidfunk.github.io/mkdocs-material/)
- [Mermaid Documentation](https://mermaid.org/intro/)
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/cfpt-mkdocs-plugins/mkdocs-table-of-figures",
"name": "mkdocs-table-of-figures",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mkdocs",
"author": "Thibaud Briard",
"author_email": "thibaud.brrd@eduge.ch",
"download_url": "https://files.pythonhosted.org/packages/51/5f/305ee1951e7ea0735cce9b74f02a7d918cfb9e87e21e9a21eb1f609e8e02/mkdocs-table-of-figures-0.3.4.tar.gz",
"platform": null,
"description": "# mkdocs-table-of-figures\n\nThis 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.\n\n## Setup\n\n### Installing using pip:\n\n`pip install mkdocs-table-of-figures`\n\n## Config\n\nYou need to activate the plugin in `mkdocs.yml`:\n\n``` yaml\nplugins:\n - table-of-figures:\n title_label: \"Table of figures of the documentation\" # Optional --> Default : Table of Figures\n figure_label: \"Figure N\u00b0\" # Optional --> Default : Figure\n description_label: \"Description of the figures\" # Optional --> Default : Description\n type_label: \"Type of the figure\" # Optional --> Default : Type\n section_label: \"Section of the figure\" # Optional --> Default : Section\n\n temp_dir: \"folder_name\" # Optional --> Default : temp_figures\n file: \"file_name\" # Optional --> Default : figures.md\n\n follow_nav_structure: true # Optional --> Default : true\n \n on_pair: true # Optional --> Default : false\n on_mermaid: true # Optional --> Default : false\n on_codeblock: true # Optional --> Default : false\n on_table: true # Optional --> Default : false\n\n show_type: true # Optional --> Default : false\n show_section: true # Optional --> Default : false\n\n image_type_name: Image Figure # Optional --> Default : Image\n pair_type_name: Pair of Images Figure # Optional --> Default : Pair\n mermaid_type_name: Mermaid Figure # Optional --> Default : Mermaid\n codeblock_type_name: Codeblock Figure # Optional --> Default : Codeblock\n table_type_name: Table Figure # Optional --> Default : Table\n```\n\nAs 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.\n\n- `title_label` - This is the title (heading 1) given to the page that will contain the table of figures.\n- `figure_label` - This is the name given to every figure right before the auto-incremented number.\n- `description_label` - This is the label given to the column containing the description of each figure (alt text).\n- `type_label` - This is the label given to the cloumn containing the type of each figure (image, mermaid, codeblock, table).\n- `section_label` - This is the label given to the cloumn containing the section of each figure (the location relative to headings and pages navigation).\n- `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.\n- `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.\n- `follow_nav_structure` - To order the figures in function of the navigation instead of alphabetical files order.\n- `on_pair` - To enable pair of image support, to use when 2 comparative image need to be next to each others.\n- `on_mermaid` - To enable `mermaid` diagrams support, need to use of `md_in_html` `Markdown` extension.\n- `on_codeblock` - To enable code blocks support, need to use of `md_in_html` `Markdown` extension.\n- `on_table` - To enable tables support, need to use of `md_in_html` `Markdown` extension.\n- `show_type` - To enable the column showing info about the type of each figure (image, mermaid, codeblock, table).\n- `show_section` - To enable the column showing info about the section of each figure (the location relative to headings and pages navigation)\n- `image_type_name` - The label shown for each figure of type image\n- `pair_type_name` - The label shown for each figure of type pair of image\n- `mermaid_type_name` - The label shown for each figure of type mermaid\n- `codeblock_type_name` - The label shown for each figure of type codeblock\n- `table_type_name` - The label shown for each figure of type table\n\n## Usage\n\nThe 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.\n\nThere is two way of correctly rendering image stored within the docs:\n\n- 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`\n- 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\n\nConcerning external images nothing change.\n\nYou can set the `md_in_html` option like so :\n\n``` yaml\nmarkdown_extensions:\n - md_in_html\n```\n\nUsing the command `mkdocs build` or `mkdocs serve` will trigger the plugin if it has been set correctly in the config file.\n\n## Support\n\n### Image like support\n\nThis plugin currently supports markdown images, pairs of images, `mermaid` diagrams, code blocks and table.\n\nTo make a pair of image you need to follow this structure:\n\n``` markdown\n|  |  |\n```\n\nThere is no need to put any alt text for the second image. it will then generate a single description for the two image:\n\n``` markdown\n|  |  |\n```\n\nTo make it work space are needed between the images and the table separator `|`\n\n### Non-image like support\n\nTo 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:\n\n``` markdown\n ``` php\n <?php\n $var = 42;\n ?>\n ```\n The title of the code block go here\n```\n\n``` markdown\n ``` mermaid\n sequenceDiagram\n participant Alice\n participant Bob\n Alice->>John: Hello John, how are you?\n loop Healthcheck\n John->>John: Fight against hypochondria\n end\n Note right of John: Rational thoughts <br/>prevail!\n John-->>Alice: Great!\n John->>Bob: How about you?\n Bob-->>John: Jolly good!\n ```\n The title of the mermaid diagram go here\n```\n\n``` markdown\n | Table | Right | Center | Left |\n | ------- | ----: | :-----: | :---- |\n | A table | With | Content | in it |\n The title of the table go here\n```\n\nIt will not work if there is a line between the element and the title.\n\nI 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.\n\nI also recommend to add this stylesheet to prevent mermaid size from being reduced or code blocks from having code centered by mkdocs-material.\n\n``` css\nfigure.figure-mermaid, figure.figure-codeblock {\n margin: 0 1em;\n width: calc(100% - 2em);\n}\n\nfigure.figure-codeblock code {\n text-align: initial;\n}\n```\n\nYou can place the stylesheet in your `mkdocs.yml` at extra-css option\n\n``` yml\nextra_css:\n - fix-mermaid-figure.css\n```\n\n### Custom attributes\n\nTo use custom attributes on images, like this :\n\n``` markdown\n{ width=\"300\" }\n```\n\nit 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](https://squidfunk.github.io/mkdocs-material/reference/images/?h=image#image-alignment-left).\n\nNote that `align=left` and `align=right` attributes will be overriden by figures style from `mkdocs-material`.\n\n## License\n\nThis project is under MIT license. See the `license` file for more details.\n\n## See Also\n\n- [GitLab Repo](http://www.gitlab.org/cfpt-mkdocs-plugins/mkdocs-table-of-figures/)\n- [MkDocs Website](http://www.mkdocs.org/)\n- [MkDocs-Material Documentation](https://squidfunk.github.io/mkdocs-material/)\n- [Mermaid Documentation](https://mermaid.org/intro/)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A MkDocs plugin listing all figures to create a table of figures page",
"version": "0.3.4",
"project_urls": {
"Homepage": "https://gitlab.com/cfpt-mkdocs-plugins/mkdocs-table-of-figures"
},
"split_keywords": [
"mkdocs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "20c2f4dc48bc87c3fd56205509646f607b36deaf6b5b9e6a60792277dc1cb485",
"md5": "63a14b55862d36e4f2ec330ead889a9f",
"sha256": "c693a50b3a065da2555647e98144bcc625bfeca1ac9c16a5ef2ae7f8ae5bf879"
},
"downloads": -1,
"filename": "mkdocs_table_of_figures-0.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "63a14b55862d36e4f2ec330ead889a9f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8281,
"upload_time": "2024-04-30T17:29:20",
"upload_time_iso_8601": "2024-04-30T17:29:20.930420Z",
"url": "https://files.pythonhosted.org/packages/20/c2/f4dc48bc87c3fd56205509646f607b36deaf6b5b9e6a60792277dc1cb485/mkdocs_table_of_figures-0.3.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "515f305ee1951e7ea0735cce9b74f02a7d918cfb9e87e21e9a21eb1f609e8e02",
"md5": "9b2b004fc9835c9853c6e3d67eee99bd",
"sha256": "655ff86988bfd9c2dc3e73c518b80a79e24d715954c181d7bffef0981f15eec9"
},
"downloads": -1,
"filename": "mkdocs-table-of-figures-0.3.4.tar.gz",
"has_sig": false,
"md5_digest": "9b2b004fc9835c9853c6e3d67eee99bd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12688,
"upload_time": "2024-04-30T17:29:22",
"upload_time_iso_8601": "2024-04-30T17:29:22.849904Z",
"url": "https://files.pythonhosted.org/packages/51/5f/305ee1951e7ea0735cce9b74f02a7d918cfb9e87e21e9a21eb1f609e8e02/mkdocs-table-of-figures-0.3.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-30 17:29:22",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "cfpt-mkdocs-plugins",
"gitlab_project": "mkdocs-table-of-figures",
"lcname": "mkdocs-table-of-figures"
}
JSON