Plugins for MkDocs.

Last update: Dec 23, 2022

Overview

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

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 @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

Comments

'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

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.

[email protected]:~/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
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

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'
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

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 ✨
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

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

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:

Markdown table:

opened by HuangFuSL 0

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:

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

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

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)
Corrects the pattern handling name and email for the contribs plugin

Adds tests for the contribs plugin

Source code(tar.gz)
Source code(zip)
css-v0.1.2.zip(37.93 KB)
v0.1.1(Oct 4, 2022)
Applies a correction over 0.1.0

Source code(tar.gz)
Source code(zip)
css-v0.1.1.zip(37.93 KB)
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:

dist-package-css.zip

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)
Fix #7

Source code(tar.gz)
Source code(zip)
v0.0.3(May 4, 2022)
Fixes bug #4

Source code(tar.gz)
Source code(zip)
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:

Install using pip install neoteroi-mkdocs

Configure this plugin in the MkDocs configuration file:

plugins: - neoteroi.mkdocsoad

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:

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

GitHub Repository

Generating a report CSV and send it to an email - Python / Django Rest Framework

Generating a report in CSV format and sending it to a email How to start project. Create a folder in your machine Create a virtual environment python3

1 Jan 17, 2022

Hjson for Python

hjson-py Hjson, a user interface for JSON Hjson works with Python 2.5+ and Python 3.3+ The Python implementation of Hjson is based on simplejson. For

185 Dec 13, 2022

script to calculate total GPA out of 4, based on input gpa.csv

gpa_calculator script to calculate total GPA out of 4 based on input gpa.csv to use, create a total.csv file containing only one integer showing the t

1 Feb 07, 2022

Data-science-on-gcp - Source code accompanying book: Data Science on the Google Cloud Platform, Valliappa Lakshmanan, O'Reilly 2017

data-science-on-gcp Source code accompanying book: Data Science on the Google Cloud Platform, 2nd Edition Valliappa Lakshmanan O'Reilly, Jan 2022 Bran

1.2k Dec 28, 2022

The Python Dict that's better than heroin.

addict addict is a Python module that gives you dictionaries whose values are both gettable and settable using attributes, in addition to standard ite

2.3k Dec 22, 2022

Documentation generator for C++ based on Doxygen and mosra/m.css.

mosra/m.css is a Doxygen-based documentation generator that significantly improves on Doxygen's default output by controlling some of Doxygen's more unruly options, supplying it's own slick HTML+CSS

109 Dec 07, 2022

Test utility for validating OpenAPI documentation

DRF OpenAPI Tester This is a test utility to validate DRF Test Responses against OpenAPI 2 and 3 schema. It has built-in support for: OpenAPI 2/3 yaml

106 Jan 05, 2023

NoVmpy - NoVmpy with python

git clone -b dev-1 https://github.com/wallds/VTIL-Python.git cd VTIL-Python py s

263 Dec 23, 2022

Sphinx Bootstrap Theme

Sphinx Bootstrap Theme This Sphinx theme integrates the Bootstrap CSS / JavaScript framework with various layout options, hierarchical menu navigation

584 Nov 16, 2022

Type hints support for the Sphinx autodoc extension

sphinx-autodoc-typehints This extension allows you to use Python 3 annotations for documenting acceptable argument types and return value types of fun

462 Dec 29, 2022

Documentation of the QR code found on new Austrian ID cards.

Austrian ID Card QR Code This document aims to be a complete documentation of the format used in the QR area on the back of new Austrian ID cards (Per

9 Dec 12, 2022

This repository outlines deploying a local Kubeflow v1.3 instance on microk8s and deploying a simple MNIST classifier using KFServing.

Zero to Inference with Kubeflow Getting Started This repository houses all of the tools, utilities, and example pipeline implementations for exploring

3 May 18, 2022

Convert excel xlsx file's table to csv file, A GUI application on top of python/pyqt and other opensource softwares.

0 Jan 20, 2022

Collections of Beautiful Latex Snippets

HandyLatex Collections of Beautiful Latex Snippets Table 👉 Succinct table with bold separation line and gray text %################## Dependencies ##

15 Apr 11, 2022

SCTYMN is a GitHub repository that includes some simple scripts(currently only python scripts) that can be useful.

Simple Codes That You Might Need SCTYMN is a GitHub repository that includes some simple scripts(currently only python scripts) that can be useful. In

2 Jan 21, 2022

Testing-crud-login-drf - Creation of an application in django on music albums

testing-crud-login-drf Creation of an application in django on music albums Befo

1 Jan 11, 2022

An open-source script written in python just for fun

Owersite Owersite is an open-source script written in python just for fun. It do

7 Sep 21, 2022

Code for our SIGIR 2022 accepted paper : P3 Ranker: Mitigating the Gaps between Pre-training and Ranking Fine-tuning with Prompt-based Learning and Pre-finetuning

P3 Ranker Implementation for our SIGIR2022 accepted paper: P3 Ranker: Mitigating the Gaps between Pre-training and Ranking Fine-tuning with Prompt-bas

14 Jan 04, 2023

LotteryBuyPredictionWebApp - Lottery Purchase Prediction Model

Lottery Purchase Prediction Model Objective and Goal Predict the lottery type th

2 Feb 14, 2022

Easy OpenAPI specs and Swagger UI for your Flask API

Flasgger Easy Swagger UI for your Flask API Flasgger is a Flask extension to extract OpenAPI-Specification from all Flask views registered in your API

3.1k Dec 24, 2022

Plugins for MkDocs.

Related tags

Overview

Plugins for MkDocs and Python Markdown

MkDocsOAD

Recommended: enable PyMDown and extra CSS

Supported sources for OpenAPI Documentation

SpanTable

SpanTable options

Styling

Comments

environment

mkdocs configuration

test file

test result

Proposal

Releases(v1.0.0)

v1.0.0(Dec 20, 2022)

v0.1.2(Oct 4, 2022)

v0.1.1(Oct 4, 2022)

v0.1.0(Oct 3, 2022)

v0.0.9(Oct 2, 2022)

v0.0.8(Oct 1, 2022)

v0.0.7(Oct 1, 2022)

v0.0.6(Aug 11, 2022)

v0.0.5(May 8, 2022)

v0.0.4(May 4, 2022)

v0.0.3(May 4, 2022)

v0.0.2(May 1, 2022)

v0.0.1(Apr 20, 2022)

MkDocsOAD

Supported sources for OpenAPI Documentation

Owner

Generating a report CSV and send it to an email - Python / Django Rest Framework

Hjson for Python

script to calculate total GPA out of 4, based on input gpa.csv

Data-science-on-gcp - Source code accompanying book: Data Science on the Google Cloud Platform, Valliappa Lakshmanan, O'Reilly 2017

The Python Dict that's better than heroin.

Documentation generator for C++ based on Doxygen and mosra/m.css.

Test utility for validating OpenAPI documentation

NoVmpy - NoVmpy with python

Sphinx Bootstrap Theme

Type hints support for the Sphinx autodoc extension

Documentation of the QR code found on new Austrian ID cards.

This repository outlines deploying a local Kubeflow v1.3 instance on microk8s and deploying a simple MNIST classifier using KFServing.

Convert excel xlsx file's table to csv file, A GUI application on top of python/pyqt and other opensource softwares.

Collections of Beautiful Latex Snippets

SCTYMN is a GitHub repository that includes some simple scripts(currently only python scripts) that can be useful.

Testing-crud-login-drf - Creation of an application in django on music albums

An open-source script written in python just for fun

Code for our SIGIR 2022 accepted paper : P3 Ranker: Mitigating the Gaps between Pre-training and Ranking Fine-tuning with Prompt-based Learning and Pre-finetuning

LotteryBuyPredictionWebApp - Lottery Purchase Prediction Model

Easy OpenAPI specs and Swagger UI for your Flask API