mkdocs-htmlproofer-plugin

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

Installation

Prerequisites

Python >= 3.6
MkDocs >= 0.17

Install the package with pip:

pip install mkdocs-htmlproofer-plugin

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.

plugins:
    - search
    - htmlproofer

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

use_directory_urls: False

Configuring

`enabled`

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

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

Which enables you do disable the plugin locally using:

export ENABLED_HTMLPROOFER=false
mkdocs serve

`raise_error`

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

plugins:
  - htmlproofer:
      raise_error: True

`raise_error_excludes`

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.

plugins:
  - search
  - htmlproofer:
      raise_error: True
      raise_error_excludes:
        504: ['https://www.mkdocs.org/']
        404: ['https://github.com/manuzhang/mkdocs-htmlproofer-plugin']
        400: ['*']

`validate_external_urls`

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.

plugins:
  - htmlproofer:
      validate_external_urls: False

`validate_rendered_template`

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.

plugins:
  - htmlproofer:
      validate_rendered_template: True

Improving

More information about plugins in the MkDocs documentation

Acknowledgement

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

Release files for mkdocs-htmlproofer-plugin 0.10.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mkdocs-htmlproofer-plugin 0.10.2
File	Size	Uploaded
mkdocs-htmlproofer-plugin-0.10.2.tar.gz	5.5 kB	Nov 24, 2022	Details

Built distribution (wheel)

Table of built distributions (wheels) for mkdocs-htmlproofer-plugin 0.10.2
File	Interpreter	ABI	Platform	Reset
mkdocs_htmlproofer_plugin-0.10.2-py3-none-any.whl 6.8 kB Nov 24, 2022	Python 3	none	any	Details

Total release size: 12.4 kB

Release files / mkdocs-htmlproofer-plugin-0.10.2.tar.gz

Download URL	mkdocs-htmlproofer-plugin-0.10.2.tar.gz
Size	5.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`11faeeaf7b75dd503d72d6ccd47778c4e68e0949737768efab24b68ef651fd19`
BLAKE2b-256 checksum How to use checksums	`33a29c1c29ae7d30d4adbfdb338ceef488192be638702ddb87240985850e6a12`
Upload date	Nov 24, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.7.3`

Release files / mkdocs_htmlproofer_plugin-0.10.2-py3-none-any.whl

Download URL	mkdocs_htmlproofer_plugin-0.10.2-py3-none-any.whl
Size	6.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`e8be2d4769abc85e54e403482d85ffdb5c0ea306d2b091a20fcfa2577e00708d`
BLAKE2b-256 checksum How to use checksums	`44a897ff0eddadc18d3c943ecde7ad8b5713f41ec031d90e1defeb0323a22214`
Upload date	Nov 24, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.7.3`