Plugins for MkDocs and Python Markdown
pip install neoteroi-mkdocs
This package includes the following plugins and extensions:
| Name | Description | Type |
|---|---|---|
mkdocsoad |
Generates documentation from OpenAPI specification files. | MkDocs plugin. |
spantable |
Tables supporting colspan and rowspan. | Python Markdown extension. |
MkDocsOAD
Plugin for MkDocs to generate human readable documentation from OpenAPI Documentation Version 3 (also known as Swagger documentation).
How to use:
- Install using
pip install neoteroi-mkdocs - Configure this plugin in the MkDocs configuration file:
plugins:
- search
- neoteroi.mkdocsoad
- Configure a source in your Markdown file, for example having a
swagger.jsonfile in yourdocsfolder:
[OAD(./docs/swagger.json)]
The plugin fetches the contents from the OpenAPI Specification source, generates Markdown using essentials-openapi, then writes them in the markdown file.
Example result:
Recommended: enable PyMDown and extra CSS
This plugin was designed to generate Markdown for sites that use Material for MkDocs and three extensions from PyMdown extensions. To achieve the best results, it is recommended to enable PyMdown extensions.
- Install PyMdown extensions using
pip install pymdown-extensions - Configure the following PyMdown markdown extensions in the MkDocs configuration file:
markdown_extensions:
- pymdownx.details
- pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
Enable PyMdown integration this way:
plugins:
- search
- neoteroi.mkdocsoad:
use_pymdownx: true
Download a local copy of the provided mkdocsoad.css file and configure it as extra file in your MkDocs configuration:
extra_css:
- css/mkdocsoad.css
Supported sources for OpenAPI Documentation
| Source | Example |
|---|---|
| YAML file | [OAD(./docs/swagger.yaml)] |
| JSON file | [OAD(./docs/swagger.json)] |
| URL returning YAML on HTTP GET | [OAD(https://example-domain.net/swagger/v1/swagger.yaml)] |
| URL returning JSON on HTTP GET | [OAD(https://example-domain.net/swagger/v1/swagger.json)] |
SpanTable
Extension for Python Markdown to support tables with colspan and rowspan, including automatic handling of span value, support for captions, and table classes.
How to use:
- Configure the extension in the MkDocs configuration file:
markdown_extensions:
- neoteroi.spantable
- Write a Markdown table like in the following example, use
@spanplaceholders for automatic handling of colspan and rowspan depending on adjacent empty cells (separator lines are ignored):
::spantable:: caption="Offices by country" class="offices-by-country"
| Country | Address |
| ------------ | -------------------------------------------------------- |
| France @span | 8 Rue St Ferréol - 92190 City: Meudon (Île-de-France) |
| | 50 boulevard Amiral Courbet - 94310 Orly (Île-de-France) |
| | ... |
| | ... |
| Italy @span | Str. S. Maurizio, 12, 10072 Caselle torinese TO |
| | S.S. Torino-Asti - 10026 Santena (TO) |
| | ... |
| Poland @span | al. Jana Pawła II 22, 00-133 Warszawa |
| | plac Trzech Krzyży 4/6, 00-535 Warszawa |
| | ... |
| | ... |
::end-spantable::
Produces an output like the following:
Note: caption and class are not required.
SpanTable options
| Option | Description |
|---|---|
| @span | Applies colspan and rowspan automatically to expand the cell to all adjacent cells (colspan has precedence over rowspan). |
| @span=x | colspan=x |
| @span=x:y | colspan=x; rowspan=y; |
| @class="value" | Adds an HTML class to any cell, to simplify styling (optional). |
| caption="value" | Adds a caption element with the given value to the table (optional). |
| class="value" | Adds a class to the table element with the given value (optional). |
In the following example, the cells with Italy and France both get colspan="2" rowspan="3" because they have empty adjacent cells growing one column and two rows:
::spantable:: caption="Life Expectancy By Current Age" class="foo"
| Italy @span | | 40 @span | | 20 @span | |
| ------------- | ----- | ------------- | ----- | ------------- | ----- |
| | | Men | Women | Men | Women |
| | | 78 | 82 | 77 | 81 |
| Poland @span | | 40 @span | | 20 @span | |
| ------------- | ----- | ------------- | ----- | ------------- | ----- |
| | | Men | Women | Men | Women |
| | | 78 | 82 | 77 | 81 |
::end-spantable::
Produces an output like the following:
Styling
Download a local copy of the provided spantable.css file and configure it as extra file in your MkDocs configuration:
extra_css:
- css/spantable.css
1.1k Dec 31, 2022
266 Dec 13, 2022
282 Dec 28, 2022
198 Jan 3, 2023
38 Feb 26, 2022
67 Jan 4, 2023
1.1k Jan 4, 2023
10 May 20, 2022
14 Sep 10, 2022
49 Jan 9, 2023
2 Sep 24, 2022
12.3k Jan 4, 2023