Builds a Hugo site and validates that there are no broken links in the site. Any broken links will be reported as a comment on the pull request.

This Action uses the stevenvachon/broken-link-checker module to crawl and report broken links.

Add a new GitHub Action to your repo. You can create a file named .github/main.workflow and use this as a quick start:

workflow "Hugo Link Check" {
  resolves = "linkcheck"
  on = "pull_request"
}

action "filter-to-pr-open-synced" {
  uses = "actions/bin/filter@master"
  args = "action 'opened|synchronize'"
}

action "linkcheck" {
  uses = "marccampbell/hugo-linkcheck-action@v0.1.0"
  needs = "filter-to-pr-open-synced"
  secrets = ["GITHUB_TOKEN"]
  env = {
    HUGO_FINAL_URL = "https://mysite.com"
  }
}

The following environment variables can be set to override defaults:

To set any of these parameters in your action, edit the "linkcheck" action step to pass these variables. For example, a main.workflow that sets a few of these would look like:

workflow "Hugo Link Check" {
  resolves = "linkcheck"
  on = "pull_request"
}

action "filter-to-pr-open-synced" {
  uses = "actions/bin/filter@master"
  args = "action 'opened|synchronize'"
}

action "linkcheck" {
  uses = "marccampbell/hugo-linkcheck-action@v0.1.0"
  needs = "filter-to-pr-open-synced"
  secrets = ["GITHUB_TOKEN"]
  env = {
    HUGO_CONFIG = "./configs/local.toml"
    HUGO_ROOT = "./hugo"
    HUGO_FINAL_URL = "https://mysite.com"
  }
}

Sometimes, it makes sense to exclude a some URLs from the broken link checker. This GitHub Action supports reading a file from the repository that contains a list of domain names or paths to exclude from the action. By default, this file is .github/hugo-linkcheck-action/exclusions.json. You can change this path by setting the environment variable HUGO_EXCLUSIONS_LIST, as documented in the table above.

This file should be a list of paths to exclude, and an example is:

[
  "server:8800",
  "microsoft.com",
  "help.mycompany.com/community/profile"
]

This GitHub Action doesn't make any assumptions about how your Hugo site is set up. There are sane defaults, which should work if you have a single Hugo site, running a relatively normal setup. But if you have a more custom Hugo setup, with various config.toml/yaml files, or content in a differerent directory than standard, use the environment variables when setting up your action.