{"id":9136,"library":"neoteroi-mkdocs","title":"Neoteroi MkDocs Plugins","description":"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.","status":"active","version":"1.2.0","language":"en","source_language":"en","source_url":"https://github.com/Neoteroi/mkdocs-plugins","tags":["mkdocs","plugin","markdown","documentation","cards","contributors","gantt","openapi"],"install":[{"cmd":"pip install neoteroi-mkdocs","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This library provides plugins for MkDocs.","package":"mkdocs","optional":false},{"reason":"Extends Python Markdown functionality within MkDocs.","package":"python-markdown","optional":false},{"reason":"Used by plugins like OpenAPI for fetching data.","package":"httpx","optional":true},{"reason":"Requires Python 3.10 or newer.","package":"python","optional":false}],"imports":[{"note":"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.","symbol":"CardsPlugin","correct":"from neoteroi_mkdocs.plugins import CardsPlugin"}],"quickstart":{"code":"mkdir my-docs\ncd my-docs\n\n# Create mkdocs.yml\ncat <<EOF > mkdocs.yml\nsite_name: My Awesome Docs\n\nplugins:\n  - neoteroi.cards\n  - neoteroi.contribs\n\n# Add some content\nEOF\n\nmkdir docs\ncat <<EOF > docs/index.md\n# Welcome to My Docs\n\nThis is a sample page using neoteroi-mkdocs plugins.\n\n<div class=\"cards\">\n  <div class=\"card\">\n    <h3>Feature One</h3>\n    <p>Description for feature one.</p>\n  </div>\n  <div class=\"card\">\n    <h3>Feature Two</h3>\n    <p>Description for feature two.</p>\n  </div>\n</div>\n\n\n<div class=\"contribs\"></div>\nEOF\n\n# Run MkDocs development server\nmkdocs serve","lang":"bash","description":"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."},"warnings":[{"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.","message":"Python 3.9 is no longer supported starting from version 1.2.0. Users running MkDocs sites with Python 3.9 will encounter errors.","severity":"breaking","affected_versions":">=1.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.1.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.1.1"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.4"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install neoteroi-mkdocs` to install the library. Verify that the plugin name in `mkdocs.yml` matches exactly, e.g., `- neoteroi.cards`.","cause":"The `neoteroi-mkdocs` library is not installed, or the plugin name in `mkdocs.yml` is misspelled.","error":"Plugin 'neoteroi.cards' not found. Please check your config and ensure the plugin is installed."},{"fix":"Upgrade your Python environment to 3.10 or a newer version. If using a virtual environment, activate one with a compatible Python version.","cause":"Attempting to run `neoteroi-mkdocs` version 1.2.0 or higher with Python 3.9 or older.","error":"This application requires Python 3.10 or greater."},{"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.","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.","error":"dateutil.parser._parser.ParseError: Unknown string format"}]}