Plugins for MkDocs and Python Markdown

pip install neoteroi-mkdocs

This package includes the following plugins and extensions:

MkDocsOAD

Plugin for MkDocs to generate human readable documentation from OpenAPI Documentation Version 3 (also known as Swagger documentation).

How to use:

1. Install using pip install neoteroi-mkdocs
2. Configure this plugin in the MkDocs configuration file:

plugins:
  - search
  - neoteroi.mkdocsoad

3. Configure a source in your Markdown file, for example having a swagger.json file in your docs folder:

[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.

1. Install PyMdown extensions using pip install pymdown-extensions
2. 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

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:

1. Configure the extension in the MkDocs configuration file:

markdown_extensions:
  - neoteroi.spantable

2. Write a Markdown table like in the following example, use @span placeholders 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

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