MkDocs Coverage Plugin

2.0.0 verified Fri May 01 auth: no python

MkDocs plugin to integrate your Coverage.py HTML report into your MkDocs site. Version 2.0.0 removes deprecated code and requires MkDocs 1.6+. It supports inserting coverage reports as new pages or into existing pages via a placeholder token.

pip install mkdocs-coverage

Common errors

error Could not find coverage report at '.../htmlcov/index.html' ↓

cause The coverage HTML report has not been generated or is in a non-default location.

fix

Run coverage html in your project root, or set the htmlcov_dir option in mkdocs.yml to point to the correct directory.

error Plugin 'coverage' is not registered ↓

cause The package is not installed or not listed in the `plugins` list in mkdocs.yml.

fix

Install mkdocs-coverage: pip install mkdocs-coverage, then add coverage under plugins in mkdocs.yml.

error No such plugin: coverage ↓

cause MkDocs cannot find the plugin entry point.

fix

Ensure mkdocs-coverage is installed and that your mkdocs.yml does not have a typo (e.g., coverge).

Warnings

breaking v2.0.0 removed deprecated code; ensure all configurations use the updated option names (e.g., `page_path` instead of `page_name`). ↓

fix Rename `page_name` to `page_path` in mkdocs.yml and any custom configurations.

deprecated The `page_name` option was deprecated in v1.2.0 and removed in v2.0.0. ↓

fix Use `page_path` instead, which supports nested paths like 'coverage/index.md'.

breaking v1.1.0 dropped support for MkDocs <1.6, requiring MkDocs 1.6+. ↓

fix Upgrade MkDocs to >=1.6.

gotcha The plugin expects the coverage HTML report to already exist before mkdocs is run. It does not generate the report itself. ↓

fix Run `coverage html` before `mkdocs build` or `mkdocs serve`.

gotcha If using the `placeholder` option, the placeholder string must be exactly `` (case-sensitive). ↓

fix Insert `` in the markdown file where the report should appear.

Imports

MkDocsCoverage

from mkdocs_coverage import MkDocsCoverage

Quickstart

Add the coverage plugin to your mkdocs.yml and run `coverage html` plus `mkdocs serve`.

# mkdocs.yml
plugins:
  - search
  - coverage