neoteroi-mkdocs 0.0.4

Plugins for MkDocs and Python Markdown

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:

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

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:

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

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