mkdocs-htmlproofer-plugin

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

Installation

0. Prerequisites

• Python >= 3.6
• MkDocs >= 0.17

1. Install the package with pip:

pip install mkdocs-htmlproofer-plugin

2. 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 first bad url status. Takes precedense over raise_error_after_finish.

plugins:
  - htmlproofer:
      raise_error: True

raise_error_after_finish

Optionally, you may want to raise an error and fail the build on at least one bad url status after all links have been checked.

plugins:
  - htmlproofer:
      raise_error_after_finish: True

raise_error_excludes

When specifying raise_error: True or raise_error_after_finish: 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

Compatibility with attr_list extension

If you need to manually specify anchors make use of the attr_list extension in the markdown. This can be useful for multilingual documentation to keep anchors as language neutral permalinks in all languages.

• A sample for a heading # Grüße {#greetings} (the slugified generated anchor Gre is overwritten with greetings).
• This also works for images this is a nice image [](foo-bar.png){#nice-image}
• And generall for paragraphs:

Listing: This is noteworthy.
{#paragraphanchor}

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.