MkDocs HTMLProofer Plugin

1.5.0 verified Fri May 01 auth: no python

A MkDocs plugin that validates URLs in rendered HTML files after build. It checks internal links, anchors, and external URLs, reporting broken links. Version 1.5.0, active development.

pip install mkdocs-htmlproofer-plugin

Common errors

error Error: The 'htmlproofer' plugin is not installed ↓

cause Plugin not installed in the Python environment.

fix

Run 'pip install mkdocs-htmlproofer-plugin'.

error ERROR - Config value 'plugins': Invalid plugin 'htmlproofer' ↓

cause Typo in plugin name or incorrect configuration.

fix

Ensure the plugin name is exactly 'htmlproofer' in mkdocs.yml.

error urllib.error.URLError: <urlopen error [Errno -2] Name or service not known> ↓

cause External URL check fails due to network issues or invalid domain.

fix

Check internet connectivity or add the URL to 'ignore_urls' in config.

Warnings

gotcha The plugin validates URLs in the built HTML, not in the Markdown source. If you have relative links that resolve correctly at build time, they may appear broken if your site is served at a different path. ↓

fix Use absolute paths or set site_url in mkdocs.yml.

deprecated Python 3.8 and 3.9 are no longer supported as of v1.5.0. ↓

fix Upgrade to Python 3.10+.

breaking As of v1.5.0, external URL checks are now parallelized by default. This may cause increased network load or rate limiting. ↓

fix Set parallelization config options (e.g., max_concurrency) if needed.

Imports

plugin
wrong
```
import mkdocs_htmlproofer_plugin
```
correct
```
# in mkdocs.yml:
plugins:
  - htmlproofer
```
This is a MkDocs plugin, not imported directly in Python code. Configure in mkdocs.yml.

Quickstart

Add the plugin to your mkdocs.yml and run mkdocs build. The plugin will validate all URLs in the output HTML.

# mkdocs.yml
plugins:
  - htmlproofer

# Build and check:
# mkdocs build