[CI] Use htmltest for link checking (#310)

Author: chalin

.gitignore

@@ -6,3 +6,5 @@
 # npm assets
 node_modules/
 package-lock.json
+
+/tmp

.htmltest.yml

@@ -0,0 +1,12 @@
+# cSpell:ignore github
+CacheExpires: 9000h # ~ 12 months
+DirectoryPath: build
+TestFilesConcurrently: true
+IgnoreDirs:
+IgnoreInternalURLs: # list of paths
+IgnoreURLs: # list of regexes of URLs or path to be ignored
+  - \?no-link-check
+  # FIXME: temporary ignore rules
+  - assistance\.md
+  - LICENSE
+  - /analyses/

Makefile

@@ -0,0 +1,56 @@
+# cSpell:ignore htmltest refcache
+# Set REFCACHE to another value to disable htmltest refcache-file manipulation
+REFCACHE?=refcache
+HTMLTEST_DIR=tmp
+HTMLTEST?=htmltest # Specify as make arg if different
+HTMLTEST_ARGS?=--log-level 1
+LINK_CACHE_FILE?=refcache.json
+LINK_CACHE_FILE_DEST_DIR?=static
+LINK_CACHE_FILE_SRC_DIR?=$(HTMLTEST_DIR)/.htmltest
+
+# 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
+
+default:
+	@echo "Make what? Target list:\n"
+	@make -rpn | grep '^[a-z]\S*:' | sed 's/://' | sort
+
+$(LINK_CACHE_FILE_SRC_DIR):
+	mkdir -p $(LINK_CACHE_FILE_SRC_DIR)
+
+$(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE):
+	mkdir -p $(LINK_CACHE_FILE_DEST_DIR)
+	echo '{}' > $(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE)
+
+refcache-restore: $(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE) $(LINK_CACHE_FILE_SRC_DIR)
+ifeq (refcache, $(REFCACHE))
+	cp $(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE) $(LINK_CACHE_FILE_SRC_DIR)/
+else
+	@echo "SKIPPING refcache-restore"
+endif
+
+refcache-save:
+ifeq (refcache, $(REFCACHE))
+	cp $(LINK_CACHE_FILE_SRC_DIR)/$(LINK_CACHE_FILE) $(LINK_CACHE_FILE_DEST_DIR)/
+	npx prettier --prose-wrap=always --write $(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE)
+else
+	@echo "SKIPPING refcache-save"
+endif
+
+check-links: $(GET_LINK_CHECKER_IF_NEEDED) \
+	refcache-restore check-links-only refcache-save
+
+check-links-only:
+	$(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

docs/analysis/howto.md

@@ -217,5 +217,5 @@ Create issues in the project documentation GitHub repository for:
 [analyses]: ../../analyses/
 [criteria]: ./criteria.md
 [project maturity level]: https://www.cncf.io/project-metrics
-[templates]: ./templates/
+[templates]: ./templates/README.md
 [issues list]: ./templates/issues-list.md

docusaurus.config.ts

@@ -24,6 +24,8 @@ const config: Config = {
   onBrokenLinks: 'warn', // TODO: 'error' or 'throw' once we've fixed all links
   onBrokenMarkdownLinks: 'warn',
 
+  trailingSlash: true,
+
   i18n: {
     defaultLocale: 'en',
     locales: ['en'],

package.json

@@ -6,7 +6,8 @@
     "_check:format:any": "npx prettier --check --ignore-path ''",
     "_check:format:delta": "npm run _check:format:any -- $(npm run -s _list:git:delta)",
     "_check:format": "npx prettier --check .",
-    "_check:links": "npx markdown-link-check --config .markdown-link-check.json",
+    "_check:links": "make --keep-going check-links",
+    "_check:links-md": "bash -c 'for f in *.md `find analyses -name \"*.md\"`; do npx [email protected] --config .markdown-link-check.json -p -v $f || exit 1; done'",
     "_check:markdown:all": "npm run -s _list:check:md | xargs -I {} -P 4 npx -p markdownlint-cli markdownlint -c .markdownlint.yaml {}",
     "_check:markdown:delta": "npm run -s _list:git:delta | xargs -I {} npx -p markdownlint-cli markdownlint -c .markdownlint.yaml {}",
     "_check:markdown:1": "npx -p markdownlint-cli markdownlint -c .markdownlint.yaml",
@@ -16,12 +17,13 @@
     "_list:check:*": "npm run --loglevel=warn | grep -Ee '^\\s*check:[^:]+$'",
     "_list:fix:*": "npm run --loglevel=warn | grep -Ee '^\\s*fix:[^:]+$' | grep -v 'fix:all'",
     "check:format": "npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)",
-    "check:links": "bash -c 'for f in *.md `find docs analyses -name \"*.md\"`; do npx [email protected] --config .markdown-link-check.json -p -v $f || exit 1; done'",
+    "check:links": "npm run _check:links",
     "check:markdown": "npm run _check:markdown:all",
     "check:spelling": "npx cspell --no-progress -c .cspell.yml analyses docs *.md",
     "check": "npm run seq -- $(npm run -s _list:check:*)",
     "fix:format": "npm run _check:format -- --write",
     "fix": "npm run seq -- $(npm -s run _list:fix:*)",
+    "precheck:links": "npm run build",
     "seq": "bash -c 'for cmd in \"$@\"; do npm run $cmd || exit 1; done' - ",
     "test": "npm run check",
     "update:pkgs": "npx npm-check-updates -u",