add broken link checker

Unfortunately we cannot use the much prettier-looking
https://github.com/tcort/markdown-link-check tool because it cannot
handle relative links to other Markdown files. For some related
discussion, see tcort/markdown-link-check#215.

So instead we just use [htmltest](https://github.com/wjdp/htmltest).
This isn't included in CI yet because we're using it to locally check
for broken links as part of the update of the "Legacy Snapshot" folder.
Later when things stabilize, we can consider adding this to CI (although
adding it CI might be not a great idea because of expected flakiness,
unless we add additional instrumentation around this).

Author: Linus Arver

site/.htmltest.yml

@@ -0,0 +1,38 @@
+IgnoreDirs:
+- /_print/
+IgnoreURLs:
+# Ignore assets and other things generated by our theme.
+- ^/favicons/
+- ^/scss/main
+- ^/js/
+# Ignore all "print view" links.
+- /_print/
+# Ignore other stuff...
+- /index.xml$
+# Ignore paths that refer to the toplevel "/docs/..." and "/community/..."
+# pages. These links are only resolvable at runtime as they refer to folder
+# names that have been normalized (the names are not what they look like in the
+# site/content/en/... path).
+- ^/docs/
+- ^/community/
+# Ignore "Last modified..." links because they break when referring to local
+# commits that have not yet been pushed up to GitHub yet.
+- ^https://github.com/kubernetes-sigs/prow/commit/
+# Ignore links that are known to be broken. This is useful if we know that a
+# link is broken but do not know how to update it.
+- ^broken:.*
+
+# Ignore github upstream docs because they give 403 even though the page exists.
+# Sadly there is no way to tell this tool to treat 403 as "OK". But, it appears
+# that these URLs can be checked with curl and its "--compressed" flag. So, we
+# have to write a script that checks all such URLs separately with curl.
+- ^https://developer.github.com/.*
+- ^https://docs.github.com/.*
+- ^https://help.github.com/.*
+
+# Ignore known-valid paths that fail for reasons unknown.
+- ^https://prow.k8s.io/badge.svg\?jobs=.*
+IgnoreDirectoryMissingTrailingSlash: true
+IgnoreSSLVerify: true
+IgnoreExternalBrokenLinks: true
+IgnoreAltMissing: true

site/Makefile

@@ -22,6 +22,9 @@ update-theme: init-theme
 	git submodule update --remote
 	npm update
 
+check-broken-links:
+	find ./public -name "*.html" -print0 | sort -z | xargs -0 ./check-broken-links.sh
+
 .PHONY: \
 	init-theme \
 	update-theme

site/check-broken-links.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Copyright 2022 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Mark all existing Markdown files with a deprecation notice and redirect link.
+
+set -euo pipefail
+
+SCRIPT_ROOT="$(cd "$(dirname "$0")" && pwd)"
+
+for file; do
+    if [[ "${file}" =~ /_print/index.html ]]; then
+        echo "skipping file ${file}"
+        continue
+    fi
+    echo "checking file ${file}"
+    htmltest -c .htmltest.yml "${file}" | sed 's/^/  /'
+    echo
+done