Plugins for MkDocs.

Overview

Build pypi versions license codecov

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
  1. 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:

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)]

Example result

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
  1. 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:

SpanTable example 1

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:

SpanTable example 2

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
Comments
  • 'str' object has no attribute 'get'

    'str' object has no attribute 'get'

    Have set up neoteroi.mkdocsoad, but when running mkdocs serve, am getting:

    ERROR    -  Error reading page 'api\api-reference-3.md': 'str' object has no attribute 'get'
    Traceback (most recent call last):
      File "C:\Users\debor\AppData\Local\Programs\Python\Python310\lib\runpy.py", line 196, in _run_module_as_main       
        return _run_code(code, main_globals, None,
      File "C:\Users\debor\AppData\Local\Programs\Python\Python310\lib\runpy.py", line 86, in _run_code
        exec(code, run_globals)
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\Scripts\mkdocs.exe\__main__.py", line 7, in <module>
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\click\core.py", line 1128, in __call__
        return self.main(*args, **kwargs)
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\click\core.py", line 1053, in main
        rv = self.invoke(ctx)
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\click\core.py", line 1659, in invoke
        return _process_result(sub_ctx.command.invoke(sub_ctx))
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\click\core.py", line 1395, in invoke
        return ctx.invoke(self.callback, **ctx.params)
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\click\core.py", line 754, in invoke
        return __callback(*args, **kwargs)
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\mkdocs\__main__.py", line 181, in serve_command  
        serve.serve(dev_addr=dev_addr, livereload=livereload, watch=watch, **kwargs)
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\mkdocs\commands\serve.py", line 63, in serve     
        config = builder()
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\mkdocs\commands\serve.py", line 58, in builder   
        build(config, live_server=live_server, dirty=dirty)
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\mkdocs\commands\build.py", line 292, in build    
        _populate_page(file.page, config, files, dirty)
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\mkdocs\commands\build.py", line 170, in _populate_page
        page.markdown = config['plugins'].run_event(
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\mkdocs\plugins.py", line 102, in run_event       
        result = method(item, **kwargs)
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\neoteroi\mkdocsoad\__init__.py", line 42, in on_page_markdown
        return self.rx.sub(self._replacer, markdown)
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\neoteroi\mkdocsoad\__init__.py", line 32, in _replacer
        return handler.write(data)
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\openapidocs\mk\v3\__init__.py", line 327, in write
        data, operations=self.get_operations(), texts=self.texts, handler=self
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\openapidocs\mk\v3\__init__.py", line 92, in get_operations
        tag = self.get_tag(path_item) or ""
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\openapidocs\mk\v3\__init__.py", line 122, in get_tag
        tags = operation.get("tags")
    AttributeError: 'str' object has no attribute 'get'
    
    opened by StarfallProjects 9
  • jinja2.exceptions.UndefinedError: 'components' is undefined

    jinja2.exceptions.UndefinedError: 'components' is undefined

    Hi !

    I tried this new add-on for mkdocs and mkdocs-material, with a swagger.json documentation coming from some AzureML endpoint API, and I get the following error when trying to serve my doc.

    mkdocs serve
    INFO     -  Building documentation...
    INFO     -  Cleaning site directory
    /home/vorph/.local/lib/python3.9/site-packages/openapidocs/mk/v3/__init__.py:204: UserWarning: Missing section in components. A security scheme referenced in a path item is not configured.
      warnings.warn(
    ERROR    -  Error reading page 'azure_ml/lesson4.md': 'components' is undefined
    Traceback (most recent call last):
      File "/home/vorph/.local/bin/mkdocs", line 8, in <module>
        sys.exit(cli())
      File "/home/vorph/.local/lib/python3.9/site-packages/click/core.py", line 1128, in __call__
        return self.main(*args, **kwargs)
      File "/home/vorph/.local/lib/python3.9/site-packages/click/core.py", line 1053, in main
        rv = self.invoke(ctx)
      File "/home/vorph/.local/lib/python3.9/site-packages/click/core.py", line 1659, in invoke
        return _process_result(sub_ctx.command.invoke(sub_ctx))
      File "/home/vorph/.local/lib/python3.9/site-packages/click/core.py", line 1395, in invoke
        return ctx.invoke(self.callback, **ctx.params)
      File "/home/vorph/.local/lib/python3.9/site-packages/click/core.py", line 754, in invoke
        return __callback(*args, **kwargs)
      File "/home/vorph/.local/lib/python3.9/site-packages/mkdocs/__main__.py", line 181, in serve_command
        serve.serve(dev_addr=dev_addr, livereload=livereload, watch=watch, **kwargs)
      File "/home/vorph/.local/lib/python3.9/site-packages/mkdocs/commands/serve.py", line 63, in serve
        config = builder()
      File "/home/vorph/.local/lib/python3.9/site-packages/mkdocs/commands/serve.py", line 58, in builder
        build(config, live_server=live_server, dirty=dirty)
      File "/home/vorph/.local/lib/python3.9/site-packages/mkdocs/commands/build.py", line 292, in build
        _populate_page(file.page, config, files, dirty)
      File "/home/vorph/.local/lib/python3.9/site-packages/mkdocs/commands/build.py", line 170, in _populate_page
        page.markdown = config['plugins'].run_event(
      File "/home/vorph/.local/lib/python3.9/site-packages/mkdocs/plugins.py", line 102, in run_event
        result = method(item, **kwargs)
      File "/home/vorph/.local/lib/python3.9/site-packages/neoteroi/mkdocsoad/__init__.py", line 42, in on_page_markdown
        return self.rx.sub(self._replacer, markdown)
      File "/home/vorph/.local/lib/python3.9/site-packages/neoteroi/mkdocsoad/__init__.py", line 32, in _replacer
        return handler.write(data)
      File "/home/vorph/.local/lib/python3.9/site-packages/openapidocs/mk/v3/__init__.py", line 326, in write
        return self._writer.write(
      File "/home/vorph/.local/lib/python3.9/site-packages/openapidocs/mk/jinja.py", line 104, in write
        return template.render(data, **kwargs)
      File "/home/vorph/.local/lib/python3.9/site-packages/jinja2/environment.py", line 1291, in render
        self.environment.handle_exception()
      File "/home/vorph/.local/lib/python3.9/site-packages/jinja2/environment.py", line 925, in handle_exception
        raise rewrite_traceback_stack(source=source)
      File "/home/vorph/.local/lib/python3.9/site-packages/openapidocs/mk/v3/views_mkdocs/layout.html", line 17, in top-level template code
        {%- if components.schemas %}
      File "/home/vorph/.local/lib/python3.9/site-packages/jinja2/environment.py", line 474, in getattr
        return getattr(obj, attribute)
    jinja2.exceptions.UndefinedError: 'components' is undefined
    make: *** [makefile:3: docs] Error 1
    

    I did follow the recommendations by enabling pymdownx and adding the extra css.

    plugins:
      - search:
          lang: fr
      - neoteroi.mkdocsoad:
          use_pymdownx: true
    
    extra_css:
      - stylesheets/mkdocsoad.css
    
    markdown_extensions:
      - pymdownx.highlight:
          linenums: true
          anchor_linenums: true
      - pymdownx.inlinehilite
      - pymdownx.superfences
      - pymdownx.snippets
      - pymdownx.tabbed:
          alternate_style: true
    

    If I remove [OAD(./includes/swagger.json)] from the markdown file where I put it, the doc is served without any problem.

    My mkdocs packages seem to be up to date.

    vorph@677d86b35cc5:~/formationML$ pip freeze | grep mkdoc
    mkdocs==1.3.0
    mkdocs-autorefs==0.4.1
    mkdocs-material==8.2.13
    mkdocs-material-extensions==1.0.3
    mkdocstrings==0.18.1
    mkdocstrings-python-legacy==0.2.2
    neoteroi-mkdocs==0.0.4
    

    Do you need any other infos that might be useful ?

    opened by MathKlim 4
  • mkdocsoad 0.1.2 breaks with empty component schemas

    mkdocsoad 0.1.2 breaks with empty component schemas

    Hey there, love the plugin for generating OpenAPI docs pages with mkdocs. I was implementing it with one of our openapi schemas and ran into an issue.

    Namely generating a docs page for a schema like either of the following will fail with parsing errors, evidently because the properties attribute in the schema is empty.

    openapi: 3.0.1
    paths:
    components:
      ...
      schemas:
        ...
        EmptyObject:
          type: object
        BrowserEventContext:
          type: object
          additionalProperties: true
    

    I believe this is still valid OpenAPI syntax and may be a parsing error within the library. If you search https://swagger.io/specification/ for "additionalProperties" you can see examples of a similar valid specification.

    Here's the relevant stack trace:

    ERROR - Error reading page 'webauthnapi/api.md': 'NoneType' object is not iterable Traceback (most recent call last): File "/Users/mikegb/.pyenv/versions/3.10.8/bin/mkdocs", line 8, in sys.exit(cli()) File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/click/core.py", line 1128, in call return self.main(*args, **kwargs) File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/click/core.py", line 1053, in main rv = self.invoke(ctx) File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/click/core.py", line 1659, in invoke return _process_result(sub_ctx.command.invoke(sub_ctx)) File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/click/core.py", line 1395, in invoke return ctx.invoke(self.callback, **ctx.params) File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/click/core.py", line 754, in invoke return __callback(*args, **kwargs) File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/mkdocs/main.py", line 234, in serve_command serve.serve(dev_addr=dev_addr, livereload=livereload, watch=watch, **kwargs) File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/mkdocs/commands/serve.py", line 82, in serve builder(config) File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/mkdocs/commands/serve.py", line 75, in builder build(config, live_server=live_server, dirty=dirty) File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/mkdocs/commands/build.py", line 308, in build _populate_page(file.page, config, files, dirty) File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/mkdocs/commands/build.py", line 177, in _populate_page page.markdown = config.plugins.run_event( File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/mkdocs/plugins.py", line 514, in run_event result = method(item, **kwargs) File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/neoteroi/mkdocsoad/init.py", line 44, in on_page_markdown return self.rx.sub(self._replacer, markdown) File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/neoteroi/mkdocsoad/init.py", line 34, in _replacer return handler.write() File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/openapidocs/mk/v3/init.py", line 417, in write return self._writer.write( File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/openapidocs/mk/jinja.py", line 107, in write return template.render(data, **kwargs) File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/jinja2/environment.py", line 1291, in render self.environment.handle_exception() File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/jinja2/environment.py", line 925, in handle_exception raise rewrite_traceback_stack(source=source) File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/openapidocs/mk/v3/views_markdown/layout.html", line 19, in top-level template code {% include "partial/components-schemas.html" %} File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/openapidocs/mk/v3/views_markdown/partial/components-schemas.html", line 5, in top-level template code {% include "partial/type.html" %} File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/openapidocs/mk/v3/views_markdown/partial/type.html", line 4, in top-level template code {%- for name, schema in handler.get_properties(definition) %} File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/openapidocs/mk/v3/init.py", line 596, in get_properties return [[key, value] for key, value in sort_dict(schema.get("properties"))] File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/openapidocs/mk/v3/init.py", line 596, in return [[key, value] for key, value in sort_dict(schema.get("properties"))] File "/Users/mikegb/.pyenv/versions/3.10.8/lib/python3.10/site-packages/openapidocs/mk/init.py", line 49, in sort_dict for key in sorted(obj, key=str.lower):

    opened by mikegb 3
  • css zip corrupted

    css zip corrupted

    Archive:  css-v0.1.2 (1).zip
      End-of-central-directory signature not found.  Either this file is not
      a zipfile, or it constitutes one disk of a multi-part archive.  In the
      latter case the central directory and zipfile comment will be found on
      the last disk(s) of this archive.
    unzip:  cannot find zipfile directory in one of css-v0.1.2 (1).zip or
            css-v0.1.2 (1).zip.zip, and cannot find css-v0.1.2 (1).zip.ZIP, period.
    
    opened by glasgowm148 3
  • No module named 'neoteroi.markdown.tables'

    No module named 'neoteroi.markdown.tables'

    Following the README, I've done pip install neoteroi-mkdocs, and then enabled both the mkdocsoad plugin, and the spantables extension. However, I'm getting:

    ERROR    -  Config value: 'markdown_extensions'. Error: No module named 'neoteroi.markdown.tables'
    Aborted with 1 Configuration Errors!
    

    Is this required for generating the open API reference? Or is it entirely separate?

    opened by StarfallProjects 2
  • mkdocs build error with python 3.7

    mkdocs build error with python 3.7

    I get the following error

    + mkdocs build
    
    Traceback (most recent call last):
    
      File "/usr/local/bin/mkdocs", line 8, in <module>
    
        sys.exit(cli())
    
      File "/usr/local/lib/python3.7/site-packages/click/core.py", line 1128, in __call__
    
        return self.main(*args, **kwargs)
    
      File "/usr/local/lib/python3.7/site-packages/click/core.py", line 1053, in main
    
        rv = self.invoke(ctx)
    
      File "/usr/local/lib/python3.7/site-packages/click/core.py", line 1659, in invoke
    
        return _process_result(sub_ctx.command.invoke(sub_ctx))
    
      File "/usr/local/lib/python3.7/site-packages/click/core.py", line 1395, in invoke
    
        return ctx.invoke(self.callback, **ctx.params)
    
      File "/usr/local/lib/python3.7/site-packages/click/core.py", line 754, in invoke
    
        return __callback(*args, **kwargs)
    
      File "/usr/local/lib/python3.7/site-packages/mkdocs/__main__.py", line 244, in build_command
    
        from mkdocs.commands import build
    
      File "/usr/local/lib/python3.7/site-packages/mkdocs/commands/build.py", line 15, in <module>
    
        from mkdocs.config.defaults import MkDocsConfig
    
      File "/usr/local/lib/python3.7/site-packages/mkdocs/config/defaults.py", line 4, in <module>
    
        from mkdocs.config import config_options as c
    
      File "/usr/local/lib/python3.7/site-packages/mkdocs/config/config_options.py", line 30, in <module>
    
        import markdown
    
      File "/usr/local/lib/python3.7/site-packages/markdown/__init__.py", line 29, in <module>
    
        from .core import Markdown, markdown, markdownFromFile  # noqa: E402
    
      File "/usr/local/lib/python3.7/site-packages/markdown/core.py", line 26, in <module>
    
        from . import util
    
      File "/usr/local/lib/python3.7/site-packages/markdown/util.py", line 87, in <module>
    
        INSTALLED_EXTENSIONS = metadata.entry_points().get('markdown.extensions', ())
    
    AttributeError: 'EntryPoints' object has no attribute 'get'
    
    opened by ktamilvanan 1
  • v1 ✨

    v1 ✨

    • Adds the possibility to specify a class for the root HTML element of cards.
    • Fixes a bug in the contribs plugin (adds a carriage return before the contribution fragment).
    • Modifies the packages to group all extensions under neoteroi.mkdocs namespace.
    • Replaces setup.py with pyproject.toml.
    opened by RobertoPrevato 0
  • Contribs plugin should add carriage return

    Contribs plugin should add carriage return

    The contribs plugin doesn´t work well if the markdown file doesn´t have an ending line. Add a carriage return if the markdown doesn´t end with a carriage return.

    opened by RobertoPrevato 0
  • Add information about default plugins

    Add information about default plugins

    To not create confusion in readers who are configuring plugins for the first time, include information about default plugins:

    plugins:
      - search  # <--
      - neoteroi.mkdocsoad:
          use_pymdownx: true
    
    opened by RobertoPrevato 0
  • Spantable: does not work with mkdocs-material admonitions

    Spantable: does not work with mkdocs-material admonitions

    Hi. I'm using mkdocs-plugins and mkdocs-material to build my personal blog. Thanks for your work, these plugins really help a lot.

    However, once when I was trying to put a table into an admonition tab provided by mkdocs-material, I found that spantable fails to be rendered inside the tab while a normal markdown table works as expected. Here is a minimal test markdown file to reproduce these results.

    environment

    • mkdocs==1.4.2
    • neoteroi-mkdocs==1.0.0
    • mkdocs-material==8.5.11

    A full environment configuration can be found here.

    mkdocs configuration

    This is a simplified configuration, only part of configuration fields are listed below. A full mkdocs configuration can be found here.

    theme:
      name: material
    
    markdown_extensions:
      - admonition
      - neoteroi.spantable
    
    extra_css:
      - https://www.neoteroi.dev/mkdocs-plugins/css/neoteroi.css
    

    test file

    Documentation of mkdocs-material admonitions can be found here.

    # Spantable test
    
    ??? note "This is a spantable"
    
        ::spantable::
    
        | 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::
    
    ??? note "This is a normal markdown table"
    
        | Country      | Address                                                  |
        | ------------ | -------------------------------------------------------- |
        | France       | 8 Rue St Ferréol - 92190 City: Meudon (Île-de-France)    |
        | Italy        | Str. S. Maurizio, 12, 10072 Caselle torinese TO          |
        | Poland       | al. Jana Pawła II 22, 00-133 Warszawa                    |
    

    test result

    Spantable:

    image

    Markdown table:

    image

    opened by HuangFuSL 0
  • Cards: Add a method of specifying a non-default image size

    Cards: Add a method of specifying a non-default image size

    I'm using card grids both as a "big link button" and for an image gallery (along with glightbox).

    I've basically used your stylesheet and hand-rolled the pages. In my own included CSS file I have an nt-gallery class, as well as nt-gallery-image and nt-gallery-title (no text class). I copied and then tweaked the settings from your own CSS file:

    .nt-card .nt-gallery-image {
        text-align: center;
        border-radius: 5px;
        background-position: center center;
        background-size: cover;
        background-repeat: no-repeat;
        min-height: 200px;
    }
    
    .nt-card .nt-gallery-image img {
        height:200px;
        margin-top:5px
    }
    
    .nt-card .nt-gallery-content {
        padding:.4rem
    }
    
    .nt-card .nt-gallery-title {
        text-align: center;
        /* font-weight: 400; */
        font-size: 0.9em;
        font-weight: 700;
        margin:4px 0 8px 0;
        line-height:20px
    }
    

    I'm using both side-by-side with good success:

    image

    You can see on top cards using nt-card-* and below the modified gallery version.

    Proposal

    I propose to add a variable to pass to the card() call with the desired image height. From there it could calculate min-height values to apply as well.

    An alternative would be a card_gallery() function that applies slightly modified styles, as I have done.

    By the way, thank you for this project. It's done wonders for my documentation.

    documentation 
    opened by jon-harper 5
  • Multiline content in Timeline plugin

    Multiline content in Timeline plugin

    Hello @RobertoPrevato, first of all congratulations for the great plugins! those are just amazing!

    I'm now playing around with the timeline plugin, and just figured out that multi lined content is only possible by typing <br/> inside the content.

    I would expect that the following snippet renders to multiple lines, as per https://yaml-multiline.info

    - content: |
        Lorem ipsum
        dolor sit amet,
        consectetur adipiscing elit.
      icon: ':fontawesome-solid-gem:'
      sub_title: 2022-Q2
      title: New features
    

    But it renders to a single one:

    image

    I'm not sure whether this is the intended behaviour or not, but raising it up here just in case.

    Thanks again for the beautiful plugins.

    Regards!

    documentation 
    opened by marcemv90 2
  • Unexpected keyword 'source' in OpenAPIV3DocumentationHandler.__init__()

    Unexpected keyword 'source' in OpenAPIV3DocumentationHandler.__init__()

    We're retrying this plugin with a single spec file (draft PR is here: https://github.com/n8n-io/n8n-docs/pull/818)

    Trying to serve locally, I'm getting:

    ERROR    -  Error reading page 'api\api-reference-3.md': OpenAPIV3DocumentationHandler.__init__() got
                an unexpected keyword argument 'source'
    Traceback (most recent call last):
      File "C:\Users\debor\AppData\Local\Programs\Python\Python310\lib\runpy.py", line 196, in _run_module_as_main
        return _run_code(code, main_globals, None,
      File "C:\Users\debor\AppData\Local\Programs\Python\Python310\lib\runpy.py", line 86, in _run_code    
        exec(code, run_globals)
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\Scripts\mkdocs.exe\__main__.py", line 7, in <module> 
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\click\core.py", line 1128, in __call__
        return self.main(*args, **kwargs)
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\click\core.py", line 1053, in main 
        rv = self.invoke(ctx)
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\click\core.py", line 1659, in invoke
        return _process_result(sub_ctx.command.invoke(sub_ctx))
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\click\core.py", line 1395, in invoke
        return ctx.invoke(self.callback, **ctx.params)
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\click\core.py", line 754, in invoke    return __callback(*args, **kwargs)
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\mkdocs\__main__.py", line 181, in serve_command
        serve.serve(dev_addr=dev_addr, livereload=livereload, watch=watch, **kwargs)
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\mkdocs\commands\serve.py", line 63, in serve
        config = builder()
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\mkdocs\commands\serve.py", line 58, in builder
        build(config, live_server=live_server, dirty=dirty)
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\mkdocs\commands\build.py", line 292, in build
        _populate_page(file.page, config, files, dirty)
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\mkdocs\commands\build.py", line 170, in _populate_page
        page.markdown = config['plugins'].run_event(
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\mkdocs\plugins.py", line 102, in run_event
        result = method(item, **kwargs)
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\neoteroi\mkdocsoad\__init__.py", line 44, in on_page_markdown
        return self.rx.sub(self._replacer, markdown)
      File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\neoteroi\mkdocsoad\__init__.py", line 31, in _replacer
        handler = OpenAPIV3DocumentationHandler(
    TypeError: OpenAPIV3DocumentationHandler.__init__() got an unexpected keyword argument 'source' 
    

    api-reference-3.md is the markdown file containing the link to the spec file.

    • Python 3.10.2
    • MkDocs 1.3.0

    Any help is appreciated :-)

    opened by StarfallProjects 3
Releases(v1.0.0)
  • v1.0.0(Dec 20, 2022)

    • Adds the possibility to specify a class for the root HTML element of cards.
    • Fixes a bug in the contribs plugin (adds a carriage return before the contribution fragment).
    • Modifies the packages to group all extensions under neoteroi.mkdocs namespace.
    • Replaces setup.py with pyproject.toml.
    Source code(tar.gz)
    Source code(zip)
    css-v1.0.0.css(37.93 KB)
  • v0.1.2(Oct 4, 2022)

  • v0.1.1(Oct 4, 2022)

  • v0.1.0(Oct 3, 2022)

    • Corrects bug in the contributors plugin, causing failures in certain CI/CD solutions and improves its safety and performance (removes shell=True!)
    • Adds option to apply a class to specific contributors, for simpler styling
    • Minor improvements to styles
    Source code(tar.gz)
    Source code(zip)
    css-v0.1.0.zip(37.93 KB)
  • v0.0.9(Oct 2, 2022)

    Improves the contributors plugin:

    • Adds the possibility to exclude contributor information (for example to not display contributions from bots).
    • Adds the possibility to merge contributors' information for cases in which the same person commits using two different email addresses.
    • Adds the possibility to display an element with the count of contributors.
    Source code(tar.gz)
    Source code(zip)
    css-v0.0.9.zip(37.89 KB)
  • v0.0.8(Oct 1, 2022)

    • Improves the Gantt extension:
      • now supports multiple periods in the same row
      • now supports activities using the start date from the previous activity (automatic dates)
    • Adds a contributors plugin (neoteroi.contribs) to display contributors' information in each page, obtaining information from the Git repository at build time
    • Increases the version of pinned dependencies (httpx and mkdocs)

    Corrects error published in v0.0.7.

    Thanks to @chrfla-cognite for his first contribution!


    CSS dist package

    Source code(tar.gz)
    Source code(zip)
    css-v0.0.8.zip(37.81 KB)
  • v0.0.7(Oct 1, 2022)

    • Improves the Gantt extension:
      • now supports multiple periods in the same row
      • now supports activities using the start date from the previous activity (automatic dates)
    • Adds a contributors plugin (neoteroi.contribs) to display contributors' information in each page, obtaining information from the Git repository at build time
    • Increases the version of pinned dependencies (httpx and mkdocs)

    Thanks to @chrfla-cognite for his first contribution!

    Source code(tar.gz)
    Source code(zip)
    css-v0.0.7.zip(37.81 KB)
  • v0.0.6(Aug 11, 2022)

    • Adds common classes to enable custom extensions reading configuration from:
      • YAML, JSON, or CSV embedded in the markdown source
      • YAML, JSON, or CSV fetched from a URL at build time (simple HTTP GET), with the option to define a custom fetcher for example for use cases that require authentication
    • Adds the Cards extension, to render cards
    • Adds the Timeline extension, to render timelines
    • Adds the Projects extension, with a control to render Gantt diagrams :sparkles:
    • Adds the link to the documentation site
    • Drops support for Python 3.7 in the build pipeline (code might still work but is not ensured)

    Downloads:

    Source code(tar.gz)
    Source code(zip)
  • v0.0.5(May 8, 2022)

    • Adds support for OAD specification organized in different files (fix https://github.com/Neoteroi/mkdocs-plugins/issues/5)
    • Improves mkdocsoad.css
    Source code(tar.gz)
    Source code(zip)
  • v0.0.4(May 4, 2022)

  • v0.0.3(May 4, 2022)

  • v0.0.2(May 1, 2022)

    • Adds the first extension for Python Markdown of the repository: spantable, custom Markdown table with support for colspan and rowspan
    • Improves the support for Material for MkDocs themes in mkdocsoad
    Source code(tar.gz)
    Source code(zip)
  • v0.0.1(Apr 20, 2022)

    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:
      - neoteroi.mkdocsoad
    
    1. 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:

    Example result

    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)] |

    Source code(tar.gz)
    Source code(zip)
Owner
Collection of open source projects for the newest versions of Python
null
:blue_book: Automatic documentation from sources, for MkDocs.

mkdocstrings Automatic documentation from sources, for MkDocs. Features Python handler features Requirements Installation Quick usage Features Languag

Timothée Mazzucotelli 1.1k Dec 31, 2022
An MkDocs plugin to export content pages as PDF files

MkDocs PDF Export Plugin An MkDocs plugin to export content pages as PDF files The pdf-export plugin will export all markdown pages in your MkDocs rep

Terry Zhao 266 Dec 13, 2022
An MkDocs plugin that simplifies configuring page titles and their order

MkDocs Awesome Pages Plugin An MkDocs plugin that simplifies configuring page titles and their order The awesome-pages plugin allows you to customize

Lukas Geiter 282 Dec 28, 2022
Generate a single PDF file from MkDocs repository.

PDF Generate Plugin for MkDocs This plugin will generate a single PDF file from your MkDocs repository. This plugin is inspired by MkDocs PDF Export P

null 198 Jan 3, 2023
MkDocs plugin for setting revision date from git per markdown file

mkdocs-git-revision-date-plugin MkDocs plugin that displays the last revision date of the current page of the documentation based on Git. The revision

Terry Zhao 48 Jan 6, 2023
A tool that allows for versioning sites built with mkdocs

mkdocs-versioning mkdocs-versioning is a plugin for mkdocs, a tool designed to create static websites usually for generating project documentation. mk

Zayd Patel 38 Feb 26, 2022
MkDocs Plugin allowing your visitors to *File > Print > Save as PDF* the entire site.

mkdocs-print-site-plugin MkDocs plugin that adds a page to your site combining all pages, allowing your site visitors to File > Print > Save as PDF th

Tim Vink 67 Jan 4, 2023
:blue_book: Automatic documentation from sources, for MkDocs.

mkdocstrings Automatic documentation from sources, for MkDocs. Features - Python handler - Requirements - Installation - Quick usage Features Language

null 1.1k Jan 4, 2023
Yet Another MkDocs Parser

yamp Motivation You want to document your project. You make an effort and write docstrings. You try Sphinx. You think it sucks and it's slow -- I did.

Max Halford 10 May 20, 2022
Dev Centric Tools for Mkdocs Based Documentation

docutools MkDocs Documentation Tools For Developers This repo is providing a set of plugins for mkdocs material compatible documentation. It is meant

Axiros GmbH 14 Sep 10, 2022
Mkdocs obsidian publish - Publish your obsidian vault through a python script

Mkdocs Obsidian Mkdocs Obsidian is an association between a python script and a

Mara 49 Jan 9, 2023
This Django app will be used to host Source.Python plugins, sub-plugins, and custom packages.

Source.Python Project Manager This Django app will be used to host Source.Python plugins, sub-plugins, and custom packages. Want to help develop this

null 2 Sep 24, 2022
A Material Design theme for MkDocs

A Material Design theme for MkDocs Create a branded static site from a set of Markdown files to host the documentation of your Open Source or commerci

Martin Donath 12.3k Jan 4, 2023
:blue_book: Automatic documentation from sources, for MkDocs.

mkdocstrings Automatic documentation from sources, for MkDocs. Features Python handler features Requirements Installation Quick usage Features Languag

Timothée Mazzucotelli 1.1k Dec 31, 2022
An MkDocs plugin to export content pages as PDF files

MkDocs PDF Export Plugin An MkDocs plugin to export content pages as PDF files The pdf-export plugin will export all markdown pages in your MkDocs rep

Terry Zhao 266 Dec 13, 2022
An MkDocs plugin that simplifies configuring page titles and their order

MkDocs Awesome Pages Plugin An MkDocs plugin that simplifies configuring page titles and their order The awesome-pages plugin allows you to customize

Lukas Geiter 282 Dec 28, 2022
Generate a single PDF file from MkDocs repository.

PDF Generate Plugin for MkDocs This plugin will generate a single PDF file from your MkDocs repository. This plugin is inspired by MkDocs PDF Export P

null 198 Jan 3, 2023
MkDocs plugin for setting revision date from git per markdown file

mkdocs-git-revision-date-plugin MkDocs plugin that displays the last revision date of the current page of the documentation based on Git. The revision

Terry Zhao 48 Jan 6, 2023
A tool that allows for versioning sites built with mkdocs

mkdocs-versioning mkdocs-versioning is a plugin for mkdocs, a tool designed to create static websites usually for generating project documentation. mk

Zayd Patel 38 Feb 26, 2022
MkDocs Plugin allowing your visitors to *File > Print > Save as PDF* the entire site.

mkdocs-print-site-plugin MkDocs plugin that adds a page to your site combining all pages, allowing your site visitors to File > Print > Save as PDF th

Tim Vink 67 Jan 4, 2023