A MkDocs plugin that validates URL in rendered HTML files
Project description
mkdocs-htmlproofer-plugin
A MkDocs plugin that validates URLs, including anchors, in rendered html files.
Installation
- Prerequisites
- Python >= 3.8
- MkDocs >= 1.4.0
- 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 thesearch
plugin. MkDocs enables it by default if there is noplugins
entry set, but now you have to enable it explicitly.
plugins:
- search
- htmlproofer
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 and status codes with raise_error_excludes
. Each URL supports unix style wildcards *
, []
, ?
, etc.
plugins:
- search
- htmlproofer:
raise_error: True
raise_error_excludes:
504: ['https://www.mkdocs.org/']
404: ['https://github.com/manuzhang/*']
400: ['*']
ignore_urls
Avoid validating the given list of URLs by ignoring them altogether. Each URL in the
list supports unix style wildcards *
, []
, ?
, etc.
Unlike raise_error_excludes
, ignored URLs will not be fetched at all.
plugins:
- search
- htmlproofer:
raise_error: True
ignore_urls:
- https://github.com/myprivateorg/*
- https://app.dynamic-service-of-some-kind.io*
warn_on_ignored_urls
Log a warning when ignoring URLs with ignore_urls
option. Defaults to false
(no warning).
plugins:
- search
- htmlproofer:
raise_error: True
ignore_urls:
- https://github.com/myprivateorg/*
- https://app.dynamic-service-of-some-kind.io*
warn_on_ignored_urls: true
ignore_pages
Avoid validating the URLs on the given list of markdown pages by ignoring them altogether.
Each page in the list supports unix style wildcards *
, []
, ?
, etc.
plugins:
- search
- htmlproofer:
raise_error: True
ignore_pages:
- path/to/file
- path/to/folder/*
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
skip_downloads
Optionally skip downloading of a remote URLs content via GET request. This can considerably reduce the time taken to validate URLs.
plugins:
- htmlproofer:
skip_downloads: 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 anchorGre
is overwritten withgreetings
). - 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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mkdocs-htmlproofer-plugin-1.3.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9d9c0830305593d5f3993f0355956bee557a7c0924d63c3caacf7924ed4f444f |
|
MD5 | 5599b7549398148720e1a71e6c3808a5 |
|
BLAKE2b-256 | 1c97ba794c328e6bf13bf8d0293e1b339d94ccaee92b402a2e67c3eb0122bb2e |
Hashes for mkdocs_htmlproofer_plugin-1.3.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 715e0648b60a92d2c838ca42deacc67c9c2a855486122cc328f573d27ceebc7c |
|
MD5 | 1e0932b54c4910b68164bab68da451a8 |
|
BLAKE2b-256 | 7fb104c7cd3c2dfb184e352ee60cfb0212644d55ac3dc82d927950f54017e692 |