Skip to main content

A MkDocs plugin that validates URL in rendered HTML files

Project description

mkdocs-htmlproofer-plugin PyPI - Version

GitHub Actions

A MkDocs plugin that validates URLs, including anchors, in rendered html files.


  1. Prerequisites
  • Python >= 3.6
  • MkDocs >= 0.17
  1. Install the package with pip:
pip install mkdocs-htmlproofer-plugin
  1. Enable the plugin in your mkdocs.yml:

Note: If you have no plugins entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugins entry set, but now you have to enable it explicitly.

    - search
    - htmlproofer

To enable cross-page anchor validation, you must set use_directory_urls = False in mkdocs.yml:

use_directory_urls: False



True by default, allows toggling whether the plugin is enabled. Useful for local development where you may want faster build times.

  - htmlproofer:
      enabled: !ENV [ENABLED_HTMLPROOFER, True]

Which enables you do disable the plugin locally using:

mkdocs serve


Optionally, you may raise an error and fail the build on bad url status.

  - htmlproofer:
      raise_error: True


When specifying raise_error: True, it is possible to ignore errors for combinations of urls ('*' means all urls) and status codes with raise_error_excludes.

  - search
  - htmlproofer:
      raise_error: True
        504: ['']
        404: ['']
        400: ['*']


Avoids validating any external URLs (i.e those starting with http:// or https://). This will be faster if you just want to validate local anchors, as it does not make any network requests.

  - htmlproofer:
      validate_external_urls: False


Validates the entire rendered template for each page - including the navigation, header, footer, etc. This defaults to off because it is much slower and often redundant to repeat for every single page.

  - htmlproofer:
      validate_rendered_template: True


More information about plugins in the MkDocs documentation


This work is based on the mkdocs-markdownextradata-plugin project and the Finding and Fixing Website Link Rot with Python, BeautifulSoup and Requests article.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs-htmlproofer-plugin-0.10.2.tar.gz (5.5 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page