Check links in the user guide (#1172)

package.json

@@ -8,6 +8,8 @@
     "build:production": "npm run cd:docs build:production",
     "build": "npm run cd:docs build",
     "cd:docs": "npm run _cd:docs -- npm run",
+    "check-links:all": "npm run cd:docs check-links:all",
+    "check-links": "npm run cd:docs check-links",
     "docs-install": "npm run _cd:docs -- npm install",
     "get:submodule": "set -x && git submodule update --init ${DEPTH:- --depth 1}",
     "serve": "npm run cd:docs serve",

userguide/.gitignore

@@ -2,3 +2,4 @@
 .hugo_build.lock
 /public
 resources/
+tmp

userguide/.htmltest.yml

@@ -0,0 +1,8 @@
+DirectoryPath: public
+CheckDoctype: false # Sadly, this is false only because of `static/google*.html`
+IgnoreAltMissing: true # FIXME
+IgnoreDirectoryMissingTrailingSlash: true # FIXME
+IgnoreDirs: [_print] # FIXME
+IgnoreEmptyHref: true # FIXME
+IgnoreInternalEmptyHash: true # FIXME
+IgnoreInternalURLs:

userguide/Makefile

@@ -0,0 +1,21 @@
+HTMLTEST_DIR=tmp
+HTMLTEST?=htmltest # Specify as make arg if different
+HTMLTEST_ARGS?=--skip-external
+
+# Use $(HTMLTEST) in PATH, if available; otherwise, we'll get a copy
+ifeq (, $(shell which $(HTMLTEST)))
+override HTMLTEST=$(HTMLTEST_DIR)/bin/htmltest
+ifeq (, $(shell which $(HTMLTEST)))
+GET_LINK_CHECKER_IF_NEEDED=get-link-checker
+endif
+endif
+
+check-links: $(GET_LINK_CHECKER_IF_NEEDED)
+	$(HTMLTEST) $(HTMLTEST_ARGS)
+
+clean:
+	rm -rf $(HTMLTEST_DIR) public/* resources
+
+get-link-checker:
+	rm -Rf $(HTMLTEST_DIR)/bin
+	curl https://htmltest.wjdp.uk | bash -s -- -b $(HTMLTEST_DIR)/bin

userguide/package.json

@@ -2,14 +2,19 @@
   "name": "docsy-user-guide",
   "scripts": {
     "_build": "npm run _hugo-dev",
+    "_check-links": "make check-links",
     "_hugo": "hugo --cleanDestinationDir --themesDir ../..",
     "_hugo-dev": "npm run _hugo -- -e dev -DFE",
     "_serve": "npm run _hugo-dev -- serve",
     "build:preview": "npm run _hugo-dev -- --minify --baseURL \"${DEPLOY_PRIME_URL:-/}\"",
     "build:production": "npm run _hugo -- --minify",
     "build": "npm run _build",
+    "check-links:all": "HTMLTEST_ARGS= npm run _check-links",
+    "check-links": "npm run _check-links",
     "clean": "rm -Rf public",
     "make:public": "git init -b main public",
+    "postbuild:preview": "npm run _check-links",
+    "postbuild:production": "npm run _check-links",
     "prepare": "cd .. && npm install",
     "serve": "npm run _serve"
   },