{"id":20823354,"url":"https://github.com/manuzhang/mkdocs-htmlproofer-plugin","last_synced_at":"2025-04-08T03:20:34.669Z","repository":{"id":45787290,"uuid":"146225188","full_name":"manuzhang/mkdocs-htmlproofer-plugin","owner":"manuzhang","description":"A MkDocs plugin that validates URL in rendered html files","archived":false,"fork":false,"pushed_at":"2024-09-23T14:54:00.000Z","size":113,"stargazers_count":44,"open_issues_count":3,"forks_count":16,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-02T00:48:45.475Z","etag":null,"topics":["mkdocs","mkdocs-plugin"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/manuzhang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-26T23:48:13.000Z","updated_at":"2024-11-26T10:31:24.000Z","dependencies_parsed_at":"2024-03-26T15:29:28.156Z","dependency_job_id":"27c4339b-9ff0-42fc-be89-3682ae858cdf","html_url":"https://github.com/manuzhang/mkdocs-htmlproofer-plugin","commit_stats":{"total_commits":118,"total_committers":16,"mean_commits":7.375,"dds":"0.48305084745762716","last_synced_commit":"4126d6d7fd1aedb1936818afa5cec466902ac8a7"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manuzhang%2Fmkdocs-htmlproofer-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manuzhang%2Fmkdocs-htmlproofer-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manuzhang%2Fmkdocs-htmlproofer-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manuzhang%2Fmkdocs-htmlproofer-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/manuzhang","download_url":"https://codeload.github.com/manuzhang/mkdocs-htmlproofer-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247767349,"owners_count":20992573,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mkdocs","mkdocs-plugin"],"created_at":"2024-11-17T22:18:11.496Z","updated_at":"2025-04-08T03:20:34.645Z","avatar_url":"https://github.com/manuzhang.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mkdocs-htmlproofer-plugin [![PyPI - Version](https://img.shields.io/pypi/v/mkdocs-htmlproofer-plugin.svg)](https://pypi.org/project/mkdocs-htmlproofer-plugin)\n\n[![GitHub Actions](https://github.com/manuzhang/mkdocs-htmlproofer-plugin/actions/workflows/ci.yml/badge.svg)](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\u003e 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 \u003e= 3.8\n* MkDocs \u003e= 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\u003e **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üße {#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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanuzhang%2Fmkdocs-htmlproofer-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmanuzhang%2Fmkdocs-htmlproofer-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanuzhang%2Fmkdocs-htmlproofer-plugin/lists"}