marccampbell/hugo-linkcheck-action

Hugo Link Check GitHub Action

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.

Quick Start

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/[email protected]"
  needs = "filter-to-pr-open-synced"
  secrets = ["GITHUB_TOKEN"]
  env = {
    HUGO_FINAL_URL = "https://mysite.com"
  }
}

Environment Variables

The following environment variables can be set to override defaults:

Name	Default Value	Description
HUGO_ACTION_COMMENT	"true"	Set to "true" or "1" to post a comment back on the pull request
HUGO_STARTUP_WAIT	15	The number of seconds to wait hugo serve to be ready
HUGO_EXCLUSIONS_LIST	.github/hugo-linkcheck-actions/exclusions.json	The path to an optional file that lists exclusions
HUGO_CONFIG	./config.toml	Path to the config.toml to use when running the site. Relative to the root of the repo
HUGO_ROOT	.	Path to the Hugo site root, relative to the repo root
HUGO_CONTENT_ROOT	./content	Path to the Hugo content directory, relative to the repo root
HUGO_FINAL_URL	http://localhost:1313	URL to show in the diff (and link to)

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/[email protected]"
  needs = "filter-to-pr-open-synced"
  secrets = ["GITHUB_TOKEN"]
  env = {
    HUGO_CONFIG = "./configs/local.toml"
    HUGO_ROOT = "./hugo"
    HUGO_FINAL_URL = "https://mysite.com"
  }
}

Excluding URLs

Sometimes, it makes sense to exclude 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"
]

Directories

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.

hugo-linkcheck-action's Issues

Status of this repository

Hey,

is this repository still maintained?
The action itself looks very useful to me but both the README as well as the number of open PRs makes me hesitate to use it.

If that isn't the case would you mind me forking and maintaining it?
I don't see a license file in the repository and I don't want to infringe on your copyright.