proof-html is a GitHub Action to validate HTML using the Nu HTML Validator through html5validator, and check links, images, and more using HTMLProofer.

- uses: anishathalye/proof-html@v2
  with:
    directory: ./site

See below for a full example.

Most of the options correspond directly to configuration options for HTMLProofer.

tokens

tokens is a JSON-encoded map of domains to authorization tokens. So it's "doubly encoded": the workflow file is written in YAML and tokens is a string (not a map!), a JSON encoding of the data. This option can be used to provide bearer tokens to use in certain scenarios, which is useful for e.g. avoiding rate limiting. Tokens are only sent to the specified websites. Note that domains must not have a trailing slash. Here is an example of an encoding of tokens:

tokens: |
  {"https://github.com": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "https://twitter.com": "yyyyyyyyyyyyyyyyyyyyyyy"}

You can also see the full example below for how to pass on the GITHUB_TOKEN supplied by the workflow runner.

swap_urls

swap_urls is a JSON-encoded map, mapping regexes to strings. This can be useful to strip a base path for an internal domain. For example:

swap_urls: |
  {"^https://example.com/": "/"}

This is the entire .github/workflows/build.yml file for a GitHub Pages / Jekyll site.

name: CI
on:
  push:
  schedule:
    - cron: '0 8 * * 6'
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-ruby@v1
        with:
          ruby-version: 2.7.x
      - uses: actions/cache@v2
        with:
          path: vendor/bundle
          key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
          restore-keys: |
            ${{ runner.os }}-gems-
      - run: |
          bundle config path vendor/bundle
          bundle install --jobs 4 --retry 3
      - run: bundle exec jekyll build
      - uses: anishathalye/proof-html@v2
        with:
          directory: ./_site
          enforce_https: false
          tokens: |
            {"https://github.com": "${{ secrets.GITHUB_TOKEN }}"}
          ignore_url: |
            http://www.example.com/
            https://en.wikipedia.org/wiki/Main_Page
          ignore_url_re: |
            ^https://twitter.com/
          swap_urls: |
            {"^https://www.anishathalye.com/": "/"}

• missing-semester/.../links.yml
• dotfiles.github.com/.../build.yml

You can build the Docker container locally with docker build . -t proof-html.

The GitHub Action is set up to pass arguments as strings through environment variables, where an argument like url_ignore is passed as INPUT_URL_IGNORE (capitalize and prepend INPUT_) to the Docker container, so you will need to do this translation yourself if you're running the Docker container locally. You can mount a local directory in the Docker container with the -v argument and pass the directory name as the INPUT_DIRECTORY argument. For example, if you compiled a site into the build directory, you can run:

docker run --rm \
    -e INPUT_DIRECTORY=build \
    -v "${PWD}/build:/build" \
    proof-html:latest

You can pass additional arguments as additional environment variables, e.g. -e INPUT_FORCE_HTTPS=0 or -e INPUT_TOKENS='{"https://github.com": "your-token-here"}'.

Copyright (c) Anish Athalye. Released under the MIT License. See LICENSE.md for details.