Neoteroi MkDocs Plugins

1.2.0 · active · verified Thu Apr 16

neoteroi-mkdocs provides a collection of plugins for MkDocs and Python Markdown, enhancing documentation sites with features like cards, contributors lists, timelines, Gantt charts, and OpenAPI specification integration. Currently at version 1.2.0, the library maintains an active development pace with regular updates and feature additions.

Common errors

```
Plugin 'neoteroi.cards' not found. Please check your config and ensure the plugin is installed.
```
cause The `neoteroi-mkdocs` library is not installed, or the plugin name in `mkdocs.yml` is misspelled.

fix Run `pip install neoteroi-mkdocs` to install the library. Verify that the plugin name in `mkdocs.yml` matches exactly, e.g., `- neoteroi.cards`.
```
This application requires Python 3.10 or greater.
```
cause Attempting to run `neoteroi-mkdocs` version 1.2.0 or higher with Python 3.9 or older.

fix Upgrade your Python environment to 3.10 or a newer version. If using a virtual environment, activate one with a compatible Python version.
```
dateutil.parser._parser.ParseError: Unknown string format
```
cause Running the `contribs` plugin (before v1.1.1) on a markdown file that hasn't been committed to Git, or has an invalid Git history, leading to parsing errors in contributor date information.

fix Upgrade `neoteroi-mkdocs` to version 1.1.1 or newer. If upgrading isn't an option, commit your files to Git before running MkDocs, or temporarily disable the `contribs` plugin for uncommitted work.

Warnings

breaking Python 3.9 is no longer supported starting from version 1.2.0. Users running MkDocs sites with Python 3.9 will encounter errors.
Fix: Upgrade your Python environment to 3.10 or newer, or pin `neoteroi-mkdocs` to a version prior to 1.2.0 if Python 3.9 is strictly required.
gotcha The `contribs` plugin can be conditionally enabled via an environment variable. If `enabled_by_env` is configured in `mkdocs.yml`, the plugin will only activate if that environment variable is set to a truthy value.
Fix: Ensure the specified environment variable (e.g., `GIT_CONTRIBS_ON`) is set before running `mkdocs serve` or `mkdocs build` if you intend for the `contribs` plugin to be active. Otherwise, remove `enabled_by_env` from your configuration.
gotcha Prior to v1.1.1, the `contribs` plugin could log `dateutil.parser.ParseError` messages when processing markdown files that were not yet committed to Git. While fixed, older versions might still exhibit this behavior.
Fix: Upgrade `neoteroi-mkdocs` to version 1.1.1 or newer to avoid log pollution when working with uncommitted files. Alternatively, commit your files before running MkDocs.
gotcha Version 1.0.4 unpinned direct dependencies like `mkdocs` and `httpx`. While this improves compatibility, it means users might encounter version conflicts if other installed packages have strict requirements for these core libraries.
Fix: If encountering dependency conflicts, use a tool like `pip-tools` (`pip-compile`) to manage and resolve your project's dependencies, or explicitly pin `mkdocs` and `httpx` to compatible versions in your `requirements.txt`.

Install

pip install neoteroi-mkdocs Install latest version

Imports

CardsPlugin
```
from neoteroi_mkdocs.plugins import CardsPlugin
```
Users typically enable plugins via `mkdocs.yml` configuration (e.g., `- neoteroi.cards`). Direct Python imports of plugin classes are for programmatic extension or specific advanced scenarios, not general usage.

Quickstart

This quickstart demonstrates how to set up a basic MkDocs project and enable two common neoteroi-mkdocs plugins: `cards` and `contribs`. It creates `mkdocs.yml` to configure the plugins and `docs/index.md` with example usage of their respective HTML/Markdown syntax. Finally, it starts the MkDocs development server to view the output.

mkdir my-docs
cd my-docs

# Create mkdocs.yml
cat <<EOF > mkdocs.yml
site_name: My Awesome Docs

plugins:
  - neoteroi.cards
  - neoteroi.contribs

# Add some content
EOF

mkdir docs
cat <<EOF > docs/index.md
# Welcome to My Docs

This is a sample page using neoteroi-mkdocs plugins.

<div class="cards">
  <div class="card">
    <h3>Feature One</h3>
    <p>Description for feature one.</p>
  </div>
  <div class="card">
    <h3>Feature Two</h3>
    <p>Description for feature two.</p>
  </div>
</div>


<div class="contribs"></div>
EOF

# Run MkDocs development server
mkdocs serve

view raw JSON →