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

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

The OpenAPI Specification Repository

Template repo to quickly make a tested and documented GitHub action in Python with Poetry

Python-slp - Side Ledger Protocol With Python

Python Deep Dive Course - Accompanying Materials

xeuledoc - Fetch information about a public Google document.

:blue_book: Automatic documentation from sources, for MkDocs.

Easy OpenAPI specs and Swagger UI for your Flask API

Pystm32ai - A Python wrapper for the stm32ai command-line tool

Manage your WordPress installation directly from SublimeText SideBar and Command Palette.

A python package to avoid writing and maintaining duplicated python docstrings.

🍭 epub generator for lightnovel.us 轻之国度 epub 生成器

A collection of simple python mini projects to enhance your python skills

This repo contains everything you'll ever need to learn/revise python basics

A curated list of awesome tools for Sphinx Python Documentation Generator

MkDocs Plugin allowing your visitors to *File > Print > Save as PDF* the entire site.

Spin-off Notice: the modules and functions used by our research notebooks have been refactored into another repository

Beautiful static documentation generator for OpenAPI/Swagger 2.0

A Python package develop for transportation spatio-temporal big data processing, analysis and visualization.

The sarge package provides a wrapper for subprocess which provides command pipeline functionality.

level2-data-annotation_cv-level2-cv-15 created by GitHub Classroom

MkDocs Plugin allowing your visitors to File > Print > Save as PDF the entire site.