mkdocs-htmlproofer-plugin

What it is and what it does

This plugin integrates into MkDocs to automatically check that all URLs and anchors in your rendered HTML documentation are valid. It can validate internal anchor links, external URLs, or both, and optionally fail your build if broken links are found. You configure it in mkdocs.yml with options to ignore specific URLs or pages, retry failed requests, and control concurrency via worker threads.

The plugin uses requests to fetch remote content and beautifulsoup4 to parse HTML and extract links. It supports wildcard patterns for excluding URLs and pages, environment variable configuration for toggling during local development, and detailed error reporting. Since MkDocs 1.6+ added native anchor validation, this plugin is most useful if you need external URL checking or more granular control over link validation behavior.

Use it for:

• Validate all internal anchor links in a large documentation site before deployment.
• Check external URLs in documentation to catch link rot and broken references.
• Fail CI/CD builds when documentation contains broken links, enforcing link quality.
• Validate documentation templates and rendered output including headers and footers.
• Exclude known-problematic URLs (private services, rate-limited APIs) while checking the rest.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A MkDocs plugin that validates URLs and anchors in rendered HTML files, checking both internal links and external URLs for correctness.

Yes, if you need external URL validation in MkDocs or want build-time link checking with fine-grained control. The plugin is actively maintained, has no vulnerabilities, and installs with low friction. However, if you only need anchor validation and are on MkDocs 1.6+, consider using MkDocs' native validation instead. Useful for documentation quality gates in CI/CD pipelines.

Install

mkdocs-htmlproofer-plugin on PyPI

pip install mkdocs-htmlproofer-plugin

uv add mkdocs-htmlproofer-plugin

poetry add mkdocs-htmlproofer-plugin

Installing mkdocs-htmlproofer-plugin

Before you install

Low friction: pure Python wheel with four runtime dependencies (mkdocs, Markdown, requests, beautifulsoup4). Actively maintained as of 2026-02-23 with no known vulnerabilities.

License in practice

MIT license (permissive); you can use, modify, and distribute this plugin freely in both open-source and proprietary projects with minimal restrictions.

Quickstart

pip install mkdocs-htmlproofer-plugin

# In mkdocs.yml:
plugins:
  - search
  - htmlproofer:
      raise_error_after_finish: true

Requires Python >= 3.10 and MkDocs >= 1.4.0; note that MkDocs 1.6+ has native anchor validation, which may overlap with this plugin's functionality.

Verify before relying

• Performance impact when validating large documentation sites with many external URLs.
• How the plugin handles rate limiting or throttling on external URL checks.
• Specific behavior when encountering redirects (301, 302, etc.) during URL validation.

Package facts

Evidence: mkdocs_htmlproofer_plugin-1.5.0-py3-none-any.whl

Keywords: mkdocs, python, markdown

Tags

More Quality Assurance packages