{"id":18046874,"url":"https://github.com/athackst/htmlproofer-action","last_synced_at":"2026-03-13T05:02:54.901Z","repository":{"id":40620026,"uuid":"376374420","full_name":"athackst/htmlproofer-action","owner":"athackst","description":"Run htmlproofer on a directory.  Defaults work with Github Pages.","archived":false,"fork":false,"pushed_at":"2025-04-03T21:20:23.000Z","size":4351,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-03T22:27:11.462Z","etag":null,"topics":["github-actions","htmlproofer"],"latest_commit_sha":null,"homepage":"https://althack.dev/htmlproofer-action","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/athackst.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2021-06-12T20:01:51.000Z","updated_at":"2025-04-03T21:20:26.000Z","dependencies_parsed_at":"2024-01-01T23:56:10.273Z","dependency_job_id":"4f4ecd25-3dfa-406a-9bb1-9c90ec312a61","html_url":"https://github.com/athackst/htmlproofer-action","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/athackst%2Fhtmlproofer-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/athackst%2Fhtmlproofer-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/athackst%2Fhtmlproofer-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/athackst%2Fhtmlproofer-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/athackst","download_url":"https://codeload.github.com/athackst/htmlproofer-action/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289128,"owners_count":20914456,"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":["github-actions","htmlproofer"],"created_at":"2024-10-30T19:09:34.682Z","updated_at":"2026-03-13T05:02:54.860Z","avatar_url":"https://github.com/athackst.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# htmlproofer-action\n\nA [GitHub Action](https://github.com/features/actions) that runs [html-proofer](https://github.com/gjtorikian/html-proofer).\n\nDefaults are set up to support jekyll + Github Pages websites.\n\n## Usage\n\nAdd this snippet to a GitHub workflow after the step that builds your site.\n\n```yaml\n- uses: athackst/htmlproofer-action@main\n```\n\n### Quickstart\n\n```yaml\n# Cache recommended to reduce frequency of external checks\n- name: Cache HTMLProofer\n  uses: actions/cache@v5\n  with:\n    path: tmp/.htmlproofer\n    key: htmlproofer\n# Run htmlproofer-action\n- uses: athackst/htmlproofer-action@main\n```\n\n### Options\n\n| Name                   | Description                                                                                                                                         | Default                                       |\n| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |\n| `directory`            | The directory to scan                                                                                                                               | ./\\_site **(required)**                       |\n| `allow_hash_href`      | If `true`, assumes `href=\"#\"` anchors are valid                                                                                                     | `true`                                        |\n| `allow_missing_href`   | If `true`, does not flag `a` tags missing `href`. In HTML5, this is technically allowed, but could also be human error.                             | `false`                                       |\n| `assume_extension`     | Automatically add specified extension to files for internal links, to allow extensionless URLs (as supported by most servers)                       | `.html`                                       |\n| `check_external_hash`  | Checks whether external hashes exist (even if the webpage exists)                                                                                   | `true`                                        |\n| `check_internal_hash`  | Checks whether internal hashes exist (even if the webpage exists)                                                                                   | `true`                                        |\n| `check_sri`            | Check that `\u003clink\u003e` and `\u003cscript\u003e` external resources use SRI                                                                                       | false                                         |\n| `directory_index_file` | Sets the file to look for when a link refers to a directory.                                                                                        | `index.html`                                  |\n| `disable_external`     | If `true`, does not run the external link checker                                                                                                   | `false`                                       |\n| `enforce_https`        | Fails a link if it's not marked as `https`.                                                                                                         | `true`                                        |\n| `extensions`           | An array of Strings indicating the file extensions you would like to check (including the dot)                                                      | `['.html']`                                   |\n| `ignore_empty_alt`     | If `true`, ignores images with empty/missing alt tags (in other words, `\u003cimg alt\u003e` and `\u003cimg alt=\"\"\u003e` are valid; set this to `false` to flag those) | `true`                                        |\n| `ignore_files`         | An array of Strings or RegExps containing file paths that are safe to ignore.                                                                       | `[]`                                          |\n| `ignore_empty_mailto`  | If `true`, allows `mailto:` `href`s which do not contain an email address.                                                                          | `false`                                       |\n| `ignore_missing_alt`   | If `true`, ignores images with missing alt tags                                                                                                     | `false`                                       |\n| `ignore_status_codes`  | A list of numbers representing status codes to ignore.                                                                                              | `[]`                                          |\n| `ignore_urls`          | A list of Strings or RegExps containing URLs that are safe to ignore. This affects all HTML attributes, such as `alt` tags on images.               | `[]`                                          |\n| `ignore_new_files`     | If `true`, will ignore any new or renamed files in the change set.                                                                                  | `true`                                        |\n| `swap_urls`            | A hash containing key-value pairs of `RegExp =\u003e String`. It transforms URLs that match `RegExp` into `String` via `gsub`.                           | `{}`                                          |\n| `host`                 | The host URL of your site so urls can be evaluated as local.                                                                                        | `${{ github.repository_owner }}.github.io`    |\n| `base_path`            | The base path of your site so urls can be evaluated as local.                                                                                       | `${{ github.event.repository.name }}`         |\n| `retries`              | Number of times to retry checking links                                                                                                             | 3                                             |\n| `cache`                | JSON configuration for HTMLProofer caching                                                                                                         | `{ \"timeframe\": { \"external\": \"2w\", \"internal\": \"1w\" } }` |\n\nThe following options are currently not supported by this action\n\n| Name              | Description                                                                                                                                     | Default |\n| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------- |\n| `log_level`       | Sets the logging level, as determined by [Yell](https://github.com/rudionrails/yell). One of `:debug`, `:info`, `:warn`, `:error`, or `:fatal`. | `:info` |\n| `only_4xx`        | Only reports errors for links that fall within the 4xx status code range.                                                                       | `false` |\n| `swap_attributes` | JSON-formatted config that maps element names to the preferred attribute to check                                                               | `{}`    |\n\n## Examples\n\n### Use with mkdocs\n\n```yaml\nname: Build and deploy Jekyll site to GitHub Pages\n\non:\n  push:\n    branches:\n      - main\n\njobs:\n  github-pages:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - name: Build and push docs\n        uses: athackst/mkdocs-simple-plugin@main\n      - name: Cache HTMLProofer\n        uses: actions/cache@v5\n        with:\n          path: tmp/.htmlproofer\n          key: htmlproofer\n      - name: Htmlproofer\n        uses: athackst/htmlproofer-action@main\n        with:\n          directory: site\n```\n\n### Use with jekyll\n\n```yaml\nname: Build Jekyll site\non:\n  push:\n    branches: [\"main\"]\npermissions:\n  contents: read\n  pages: write\n  id-token: write\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v6\n      - name: Setup Pages\n        id: pages\n        uses: actions/configure-pages@v3\n      - name: Build\n        uses: actions/jekyll-build-pages@v1\n      - name: Cache HTMLProofer\n        uses: actions/cache@v5\n        with:\n          path: tmp/.htmlproofer\n          key: htmlproofer\n      - name: HTMLProofer\n        uses: athackst/htmlproofer-action@main\n        with:\n          host: ${{ steps.pages.outputs.host }}\n          base_path: ${{ steps.pages.outputs.base_path }}\n      - name: Upload artifact\n        uses: actions/upload-pages-artifact@v1\n  deploy:\n    runs-on: ubuntu-latest\n    needs: build\n    if: github.ref == 'refs/heads/main'\n    steps:\n      - name: Deploy to GitHub Pages\n        id: deployment\n        uses: actions/deploy-pages@v2\n    environment:\n      name: github-pages\n      url: ${{ steps.deployment.outputs.page_url }}\n```\n\n### Ignore a url\n\nThis uses the same syntax as htmlproofer, but you can either use a comma or new line to separate values.\n\n```yaml\n- name: Htmlproofer\n  uses: athackst/htmlproofer-action@main\n  with:\n    ignore_urls: |\n      /twitter.com/\n      https://fonts.gstatic.com\n```\n\n### Enable HTMLProofer cache with GitHub Actions cache\n\n```yaml\n- name: Cache HTMLProofer\n  uses: actions/cache@v3\n  with:\n    path: tmp/.htmlproofer\n    key: ${{ runner.os }}-htmlproofer\n- name: Htmlproofer\n  uses: athackst/htmlproofer-action@main\n  with:\n    cache: '{ \"timeframe\": { \"external\": \"2w\", \"internal\": \"1w\" } }'\n```\n\nWhen caching is enabled, the action prints a cache summary in the logs and includes it in the GitHub step summary.\n\n### Swap a URL\n\nThis swaps urls so that local base name and version numbers are disregarded in url links\n\n```yaml\n- name: Htmlproofer\n  uses: athackst/htmlproofer-action@main\n  with:\n    directory: site\n    url_swap: |\n      ^https.?\\/\\/.*.github.io\\/${{ github.event.repository.name }}:\n      ^\\/${{ github.event.repository.name }}:\n      ^\\/dev:\n      ^\\/v\\d+\\.\\d+\\.\\d+:\n```\n\n## Local Docker\n\nYou can also run this locally using the docker image. This can be helpful in understanding errors.\n\nI make a local alias that calls the Docker image with environment variables set based on my common use cases.\n\n```sh\nfunction htmlproofer_action() {\n        curr_dir=\"$PWD/$1\"\n        echo \"Running on $curr_dir\"\n        base_dir=$(basename \"$PWD\")\n        url_swap=\"^\\/${base_dir}:,^\\/dev:,^\\/v\\d+\\.\\d+\\.\\d+:\"\n        docker run -v ${curr_dir}:/site -e INPUT_URL_SWAP=${url_swap} althack/htmlproofer:latest\n}\n```\n\nThen I can just go to the folder the site is built in and run the htmlproofer.\n\n```bash\nhtmlproofer _site\n```\n\n## License\n\nThis software is licensed under [Apache 2.0](https://github.com/athackst/htmlproofer-action/blob/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fathackst%2Fhtmlproofer-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fathackst%2Fhtmlproofer-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fathackst%2Fhtmlproofer-action/lists"}