# mkdocs-htmlproofer-plugin [](https://pypi.org/project/mkdocs-htmlproofer-plugin)
[](https://github.com/manuzhang/mkdocs-htmlproofer-plugin/actions/workflows/ci.yml)
*A [MkDocs](https://www.mkdocs.org/) plugin that validates URLs, including anchors, in rendered html files*.
> Note: [MkDocs 1.6+ supports native validation of anchors](https://www.mkdocs.org/user-guide/configuration/#validation).
## Installation
0. Prerequisites
* Python >= 3.8
* MkDocs >= 1.4.0
1. Install the package with pip:
```bash
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.
```yaml
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.
```yaml
plugins:
- htmlproofer:
enabled: !ENV [ENABLED_HTMLPROOFER, True]
```
Which enables you do disable the plugin locally using:
```bash
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`.
```yaml
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.
```yaml
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.
```yaml
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.
```yaml
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).
```yaml
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.
```yaml
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.
```yaml
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.
```yaml
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.
```yaml
plugins:
- htmlproofer:
skip_downloads: True
```
## Compatibility with `attr_list` extension
If you need to manually specify anchors make use of the `attr_list` [extension](https://python-markdown.github.io/extensions/attr_list) 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:
```markdown
Listing: This is noteworthy.
{#paragraphanchor}
```
## Improving
More information about plugins in the [MkDocs documentation](http://www.mkdocs.org/user-guide/plugins/)
## Acknowledgement
This work is based on the [mkdocs-markdownextradata-plugin](https://github.com/rosscdh/mkdocs-markdownextradata-plugin) project and the [Finding and Fixing Website Link Rot with Python, BeautifulSoup and Requests](https://www.twilio.com/en-us/blog/find-fix-website-link-rot-python-beautifulsoup-requests-html) article.
Raw data
{
"_id": null,
"home_page": "https://github.com/manuzhang/mkdocs-htmlproofer-plugin",
"name": "mkdocs-htmlproofer-plugin",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mkdocs python markdown",
"author": "Manu Zhang",
"author_email": "owenzhang1990@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1c/97/ba794c328e6bf13bf8d0293e1b339d94ccaee92b402a2e67c3eb0122bb2e/mkdocs-htmlproofer-plugin-1.3.0.tar.gz",
"platform": null,
"description": "# mkdocs-htmlproofer-plugin [](https://pypi.org/project/mkdocs-htmlproofer-plugin)\n\n[](https://github.com/manuzhang/mkdocs-htmlproofer-plugin/actions/workflows/ci.yml)\n\n*A [MkDocs](https://www.mkdocs.org/) plugin that validates URLs, including anchors, in rendered html files*.\n\n> Note: [MkDocs 1.6+ supports native validation of anchors](https://www.mkdocs.org/user-guide/configuration/#validation).\n\n## Installation\n\n0. Prerequisites\n\n* Python >= 3.8\n* MkDocs >= 1.4.0\n\n1. Install the package with pip:\n\n```bash\npip install mkdocs-htmlproofer-plugin\n```\n\n2. Enable the plugin in your `mkdocs.yml`:\n\n> **Note:** If you have no `plugins` entry in your config file yet, you'll likely also want to add the `search` plugin.\nMkDocs enables it by default if there is no `plugins` entry set, but now you have to enable it explicitly.\n\n```yaml\nplugins:\n - search\n - htmlproofer\n```\n\n## Configuring\n\n### `enabled`\n\nTrue by default, allows toggling whether the plugin is enabled.\nUseful for local development where you may want faster build times.\n\n```yaml\nplugins:\n - htmlproofer:\n enabled: !ENV [ENABLED_HTMLPROOFER, True]\n```\n\nWhich enables you do disable the plugin locally using:\n\n```bash\nexport ENABLED_HTMLPROOFER=false\nmkdocs serve\n```\n\n\n### `raise_error`\n\nOptionally, you may raise an error and fail the build on first bad url status. Takes precedense over `raise_error_after_finish`.\n\n```yaml\nplugins:\n - htmlproofer:\n raise_error: True\n```\n\n### `raise_error_after_finish`\n\nOptionally, you may want to raise an error and fail the build on at least one bad url status after all links have been checked.\n\n```yaml\nplugins:\n - htmlproofer:\n raise_error_after_finish: True\n```\n\n### `raise_error_excludes`\n\nWhen specifying `raise_error: True` or `raise_error_after_finish: True`, it is possible to ignore errors\nfor combinations of URLs and status codes with `raise_error_excludes`. Each URL supports unix style wildcards `*`, `[]`, `?`, etc.\n\n```yaml\nplugins:\n - search\n - htmlproofer:\n raise_error: True\n raise_error_excludes:\n 504: ['https://www.mkdocs.org/']\n 404: ['https://github.com/manuzhang/*']\n 400: ['*']\n```\n\n### `ignore_urls`\n\nAvoid validating the given list of URLs by ignoring them altogether. Each URL in the\nlist supports unix style wildcards `*`, `[]`, `?`, etc.\n\nUnlike `raise_error_excludes`, ignored URLs will not be fetched at all.\n\n```yaml\nplugins:\n - search\n - htmlproofer:\n raise_error: True\n ignore_urls:\n - https://github.com/myprivateorg/*\n - https://app.dynamic-service-of-some-kind.io*\n```\n\n### `warn_on_ignored_urls`\n\nLog a warning when ignoring URLs with `ignore_urls` option. Defaults to `false` (no warning).\n\n```yaml\nplugins:\n - search\n - htmlproofer:\n raise_error: True\n ignore_urls:\n - https://github.com/myprivateorg/*\n - https://app.dynamic-service-of-some-kind.io*\n warn_on_ignored_urls: true\n```\n\n### `ignore_pages`\n\nAvoid validating the URLs on the given list of markdown pages by ignoring them altogether.\nEach page in the list supports unix style wildcards `*`, `[]`, `?`, etc.\n\n```yaml\nplugins:\n - search\n - htmlproofer:\n raise_error: True\n ignore_pages:\n - path/to/file\n - path/to/folder/*\n```\n\n### `validate_external_urls`\n\nAvoids validating any external URLs (i.e those starting with http:// or https://).\nThis will be faster if you just want to validate local anchors, as it does not make any network requests.\n\n```yaml\nplugins:\n - htmlproofer:\n validate_external_urls: False\n```\n\n### `validate_rendered_template`\n\nValidates the entire rendered template for each page - including the navigation, header, footer, etc.\nThis defaults to off because it is much slower and often redundant to repeat for every single page.\n\n```yaml\nplugins:\n - htmlproofer:\n validate_rendered_template: True\n```\n\n### `skip_downloads`\n\nOptionally skip downloading of a remote URLs content via GET request. This can\nconsiderably reduce the time taken to validate URLs.\n\n```yaml\nplugins:\n - htmlproofer:\n skip_downloads: True\n```\n\n## Compatibility with `attr_list` extension\n\nIf you need to manually specify anchors make use of the `attr_list` [extension](https://python-markdown.github.io/extensions/attr_list) in the markdown.\nThis can be useful for multilingual documentation to keep anchors as language neutral permalinks in all languages.\n\n* A sample for a heading `# Gr\u00fc\u00dfe {#greetings}` (the slugified generated anchor `Gre` is overwritten with `greetings`).\n* This also works for images `this is a nice image [](foo-bar.png){#nice-image}`\n* And generall for paragraphs:\n```markdown\nListing: This is noteworthy.\n{#paragraphanchor}\n```\n\n## Improving\n\nMore information about plugins in the [MkDocs documentation](http://www.mkdocs.org/user-guide/plugins/)\n\n## Acknowledgement\n\nThis work is based on the [mkdocs-markdownextradata-plugin](https://github.com/rosscdh/mkdocs-markdownextradata-plugin) project and the [Finding and Fixing Website Link Rot with Python, BeautifulSoup and Requests](https://www.twilio.com/en-us/blog/find-fix-website-link-rot-python-beautifulsoup-requests-html) article.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A MkDocs plugin that validates URL in rendered HTML files",
"version": "1.3.0",
"project_urls": {
"Homepage": "https://github.com/manuzhang/mkdocs-htmlproofer-plugin"
},
"split_keywords": [
"mkdocs",
"python",
"markdown"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7fb104c7cd3c2dfb184e352ee60cfb0212644d55ac3dc82d927950f54017e692",
"md5": "1e0932b54c4910b68164bab68da451a8",
"sha256": "715e0648b60a92d2c838ca42deacc67c9c2a855486122cc328f573d27ceebc7c"
},
"downloads": -1,
"filename": "mkdocs_htmlproofer_plugin-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1e0932b54c4910b68164bab68da451a8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8920,
"upload_time": "2024-09-13T14:46:07",
"upload_time_iso_8601": "2024-09-13T14:46:07.303802Z",
"url": "https://files.pythonhosted.org/packages/7f/b1/04c7cd3c2dfb184e352ee60cfb0212644d55ac3dc82d927950f54017e692/mkdocs_htmlproofer_plugin-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1c97ba794c328e6bf13bf8d0293e1b339d94ccaee92b402a2e67c3eb0122bb2e",
"md5": "5599b7549398148720e1a71e6c3808a5",
"sha256": "9d9c0830305593d5f3993f0355956bee557a7c0924d63c3caacf7924ed4f444f"
},
"downloads": -1,
"filename": "mkdocs-htmlproofer-plugin-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "5599b7549398148720e1a71e6c3808a5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8804,
"upload_time": "2024-09-13T14:46:09",
"upload_time_iso_8601": "2024-09-13T14:46:09.097013Z",
"url": "https://files.pythonhosted.org/packages/1c/97/ba794c328e6bf13bf8d0293e1b339d94ccaee92b402a2e67c3eb0122bb2e/mkdocs-htmlproofer-plugin-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-13 14:46:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "manuzhang",
"github_project": "mkdocs-htmlproofer-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-htmlproofer-plugin"
}
JSON
