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.

Note: MkDocs 1.6+ supports native validation of anchors.

Installation

  1. Prerequisites
  • Python >= 3.8
  • MkDocs >= 1.4.0
  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.

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 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.

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-1.3.0.tar.gz (8.8 kB view details)

Uploaded Source

Built Distribution

File details

Details for the file mkdocs-htmlproofer-plugin-1.3.0.tar.gz.

File metadata

File hashes

Hashes for mkdocs-htmlproofer-plugin-1.3.0.tar.gz
Algorithm Hash digest
SHA256 9d9c0830305593d5f3993f0355956bee557a7c0924d63c3caacf7924ed4f444f
MD5 5599b7549398148720e1a71e6c3808a5
BLAKE2b-256 1c97ba794c328e6bf13bf8d0293e1b339d94ccaee92b402a2e67c3eb0122bb2e

See more details on using hashes here.

File details

Details for the file mkdocs_htmlproofer_plugin-1.3.0-py3-none-any.whl.

File metadata

File hashes

Hashes for mkdocs_htmlproofer_plugin-1.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 715e0648b60a92d2c838ca42deacc67c9c2a855486122cc328f573d27ceebc7c
MD5 1e0932b54c4910b68164bab68da451a8
BLAKE2b-256 7fb104c7cd3c2dfb184e352ee60cfb0212644d55ac3dc82d927950f54017e692

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page