---
id: mkdocs-htmlproofer-plugin
version: "1.5.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# mkdocs-htmlproofer-plugin — A MkDocs plugin that validates URL in rendered HTML files

License: permissive · Maintenance: active · Downloads: 96.9K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 96.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

mkdocs link validation, url checker plugin, anchor validation markdown, broken link detection, html proofreader, mkdocs url validator, link rot detection, documentation-quality, ci-cd-integration, link-validation

[View on SkillFed](https://skillfed.io/packages/mkdocs-htmlproofer-plugin) · [View on PyPI](https://pypi.org/project/mkdocs-htmlproofer-plugin/)