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

A tutorial for people to run synthetic data replica's from source healthcare datasets

Synthetic-Data-Replica-for-Healthcare Description What is this? A tailored hands-on tutorial showing how to use Python to create synthetic data replic

11 Mar 22, 2022

Compare two CSV files for differences. Colorize the differences and align the columns.

pretty-csv-diff Compare two CSV files for differences. Colorize the differences and align the columns. Command-Line Example Command-Line Usage usage:

6 Dec 29, 2022

OpenTelemetry Python API and SDK

Getting Started • API Documentation • Getting In Touch (GitHub Discussions) Contributing • Examples OpenTelemetry Python This page describes the Pytho

1.1k Jan 08, 2023

Count the number of lines of code in a directory, minus the irrelevant stuff

countloc Simple library to count the lines of code in a directory (excluding stuff like node_modules) Simply just run: countloc node_modules args to

4 Feb 14, 2022

Minimal reproducible example for `mkdocstrings` Python handler issue

0 Feb 17, 2022

Bring RGB to life in Neovim

Bring RGB to life in Neovim Change your RGB devices' color depending on Neovim's mode. Fast and asynchronous plugin to live your vim-life to the fulle

40 Oct 27, 2022

A Python library for setting up projects using tabular data.

A Python library for setting up projects using tabular data. It can create project folders, standardize delimiters, and convert files to CSV from either individual files or a directory.

0 Dec 13, 2022

A simple flask application to collect annotations for the Turing Change Point Dataset, a benchmark dataset for change point detection algorithms

AnnotateChange Welcome to the repository of the "AnnotateChange" application. This application was created to collect annotations of time series data

16 Jul 21, 2022

A fast time mocking alternative to freezegun that wraps libfaketime.

python-libfaketime: fast date/time mocking python-libfaketime is a wrapper of libfaketime for python. Some brief details: Linux and OS X, Pythons 3.5

68 Jun 10, 2022

python wrapper for simple-icons

simpleicons Use a wide-range of icons derived from the simple-icons repo in python. Go to their website for a full list of icons. The slug version mus

14 Nov 07, 2022

Sphinx theme for readthedocs.org

Read the Docs Sphinx Theme This Sphinx theme was designed to provide a great reader experience for documentation users on both desktop and mobile devi

4.3k Dec 31, 2022

A PyTorch implementation of Deep SAD, a deep Semi-supervised Anomaly Detection method.

Deep SAD: A Method for Deep Semi-Supervised Anomaly Detection This repository provides a PyTorch implementation of the Deep SAD method presented in ou

276 Jan 04, 2023

Uses diff command to compare expected output with student's submission output

AUTOGRADER for GRADESCOPE using diff with partial grading Description: Uses diff command to compare expected output with student's submission output U

2 Jan 11, 2022

Docov - Light-weight, recursive docstring coverage analysis for python modules

docov Light-weight, recursive docstring coverage analysis for python modules. Ov

3 Feb 04, 2022

Cleaner script to normalize knock's output EPUBs

clean-epub The excellent knock application by Benton Edmondson outputs EPUBs that seem to be DRM-free. However, if you run the application twice on th

2 Dec 16, 2022

This is the repository that includes the code material for the ESweek 2021 for the Education Class Lecture A3 "Learn to Drive (and Race!) Autonomous Vehicles"

ESweek2021_educationclassA3 This is the repository that includes the code material for the ESweek 2021 for the Education Class Lecture A3 "Learn to Dr

29 Dec 06, 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

A tutorial for people to run synthetic data replica's from source healthcare datasets

Compare two CSV files for differences. Colorize the differences and align the columns.

OpenTelemetry Python API and SDK

Count the number of lines of code in a directory, minus the irrelevant stuff

Minimal reproducible example for `mkdocstrings` Python handler issue

Bring RGB to life in Neovim

A Python library for setting up projects using tabular data.

A simple flask application to collect annotations for the Turing Change Point Dataset, a benchmark dataset for change point detection algorithms

A fast time mocking alternative to freezegun that wraps libfaketime.

python wrapper for simple-icons

Sphinx theme for readthedocs.org

A PyTorch implementation of Deep SAD, a deep Semi-supervised Anomaly Detection method.

Uses diff command to compare expected output with student's submission output

Docov - Light-weight, recursive docstring coverage analysis for python modules

Cleaner script to normalize knock's output EPUBs

This is the repository that includes the code material for the ESweek 2021 for the Education Class Lecture A3 "Learn to Drive (and Race!) Autonomous Vehicles"

advance python series: Data Classes, OOPs, python

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

A tool that allows for versioning sites built with mkdocs

Always know what to expect from your data.