From 892da55d4e126f079eed2eb4319375042ec14e57 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 17 May 2026 20:10:36 +0200
Subject: [PATCH 1/3] Add a python-based link checker that works a wee bit
 faster than Lychee.

---
 docs/check.bat                                |  14 +-
 docs/lychee.bat                               |  45 ++
 .../lcheck-fixture/site/assets/script.js      |   1 +
 .../lcheck-fixture/site/assets/style.css      |   1 +
 .../site/good-dir-noindex/other.html          |   2 +
 .../lcheck-fixture/site/good-dir/index.html   |   3 +
 .../lcheck-fixture/site/good-fallback.html    |   2 +
 .../lcheck-fixture/site/good-fragments.html   |   4 +
 experiments/lcheck-fixture/site/good.html     |   3 +
 experiments/lcheck-fixture/site/index.html    |  63 +++
 .../lcheck-fixture/site/subdir/image.png      |   1 +
 .../lcheck-fixture/site/subdir/nested.html    |   4 +
 requirements.txt                              |   1 +
 scripts/check_links.py                        | 401 ++++++++++++++++++
 14 files changed, 541 insertions(+), 4 deletions(-)
 create mode 100644 docs/lychee.bat
 create mode 100644 experiments/lcheck-fixture/site/assets/script.js
 create mode 100644 experiments/lcheck-fixture/site/assets/style.css
 create mode 100644 experiments/lcheck-fixture/site/good-dir-noindex/other.html
 create mode 100644 experiments/lcheck-fixture/site/good-dir/index.html
 create mode 100644 experiments/lcheck-fixture/site/good-fallback.html
 create mode 100644 experiments/lcheck-fixture/site/good-fragments.html
 create mode 100644 experiments/lcheck-fixture/site/good.html
 create mode 100644 experiments/lcheck-fixture/site/index.html
 create mode 100644 experiments/lcheck-fixture/site/subdir/image.png
 create mode 100644 experiments/lcheck-fixture/site/subdir/nested.html
 create mode 100644 requirements.txt
 create mode 100644 scripts/check_links.py

diff --git a/docs/check.bat b/docs/check.bat
index 6d19e3bb..094bbce5 100644
--- a/docs/check.bat
+++ b/docs/check.bat
@@ -1,6 +1,12 @@
-@rem Use lychee to check the links in both build outputs, then scan
+@rem Run the Python-based link checker on both build outputs, then scan
 @rem _site-offline/ for live-site links that survived offlinify.
 @rem
+@rem Same arguments as lychee.bat -- only the executable differs. The Python
+@rem script is faster on this workload (~25x on Windows) and a bit stricter:
+@rem it flags <script src> targets that don't exist and rejects trailing
+@rem slashes on file-shaped URLs (e.g. `foo.html/`), both of which lychee
+@rem silently accepts. lychee.bat remains available as a second opinion.
+@rem
 @rem _site/        Online tree. `--fallback-extensions html` mirrors what
 @rem               GitHub Pages does at request time: an extensionless
 @rem               URL like /FAQ is served as /FAQ.html. Without the flag
@@ -23,9 +29,9 @@
 @rem script exits non-zero if any fails (earlier failures take precedence
 @rem in the reported code).
 @setlocal
-@set LYCHEE="%~dp0..\.claude\lychee.exe"
+@set CHECK=python "%~dp0..\scripts\check_links.py"
 @echo Checking _site/ (online) ...
-@%LYCHEE% --offline --include-fragments --fallback-extensions html --index-files "index.html,." --root-dir ".\_site" ".\_site" %*
+@%CHECK% --offline --include-fragments --fallback-extensions html --index-files "index.html,." --root-dir ".\_site" ".\_site" %*
 @set EXIT1=%ERRORLEVEL%
 @echo.
 @echo Checking _site-offline/ (offline) ...
@@ -34,7 +40,7 @@
 @rem above accepts `.` because GitHub Pages can serve an unstyled
 @rem directory listing or a 404 in that case; offline, there's no
 @rem such fallback, and the link is just broken.
-@%LYCHEE% --offline --include-fragments --index-files "index.html" --root-dir ".\_site-offline" ".\_site-offline" %*
+@%CHECK% --offline --include-fragments --index-files "index.html" --root-dir ".\_site-offline" ".\_site-offline" %*
 @set EXIT2=%ERRORLEVEL%
 @echo.
 @echo Checking _site-offline/ for live-site links ...
diff --git a/docs/lychee.bat b/docs/lychee.bat
new file mode 100644
index 00000000..6d19e3bb
--- /dev/null
+++ b/docs/lychee.bat
@@ -0,0 +1,45 @@
+@rem Use lychee to check the links in both build outputs, then scan
+@rem _site-offline/ for live-site links that survived offlinify.
+@rem
+@rem _site/        Online tree. `--fallback-extensions html` mirrors what
+@rem               GitHub Pages does at request time: an extensionless
+@rem               URL like /FAQ is served as /FAQ.html. Without the flag
+@rem               every pretty permalink would appear broken.
+@rem _site-offline/ Offline tree. No extension fallback -- every link must
+@rem               resolve to an actual file under file://, since the
+@rem               browser does no rewriting. Catches relative links in
+@rem               markdown sources whose permalink shape doesn't match
+@rem               the rendered filename (e.g. `[Foo](Foo/)` when Jekyll
+@rem               wrote `Foo.html`, not `Foo/index.html`).
+@rem live-links   Greps _site-offline/ HTML for any surviving
+@rem               https://docs.twinbasic.com reference outside <code> /
+@rem               <pre> blocks. After _plugins/offlinify.rb strips the
+@rem               jekyll-seo-tag block from each page, none should
+@rem               remain -- a hit means a source link goes to the live
+@rem               site instead of the canonical /tB/... permalink.
+@rem               See ../scripts/check_offline_live_links.py.
+@rem
+@rem All three checks always run so you see all errors in one pass; the
+@rem script exits non-zero if any fails (earlier failures take precedence
+@rem in the reported code).
+@setlocal
+@set LYCHEE="%~dp0..\.claude\lychee.exe"
+@echo Checking _site/ (online) ...
+@%LYCHEE% --offline --include-fragments --fallback-extensions html --index-files "index.html,." --root-dir ".\_site" ".\_site" %*
+@set EXIT1=%ERRORLEVEL%
+@echo.
+@echo Checking _site-offline/ (offline) ...
+@rem No `.` in --index-files: under file://, a bare directory URL
+@rem (`Foo/`) requires an actual index.html inside. The online check
+@rem above accepts `.` because GitHub Pages can serve an unstyled
+@rem directory listing or a 404 in that case; offline, there's no
+@rem such fallback, and the link is just broken.
+@%LYCHEE% --offline --include-fragments --index-files "index.html" --root-dir ".\_site-offline" ".\_site-offline" %*
+@set EXIT2=%ERRORLEVEL%
+@echo.
+@echo Checking _site-offline/ for live-site links ...
+@python "%~dp0..\scripts\check_offline_live_links.py"
+@set EXIT3=%ERRORLEVEL%
+@if %EXIT1% NEQ 0 exit /b %EXIT1%
+@if %EXIT2% NEQ 0 exit /b %EXIT2%
+@exit /b %EXIT3%
diff --git a/experiments/lcheck-fixture/site/assets/script.js b/experiments/lcheck-fixture/site/assets/script.js
new file mode 100644
index 00000000..172f1ae6
--- /dev/null
+++ b/experiments/lcheck-fixture/site/assets/script.js
@@ -0,0 +1 @@
+// noop
diff --git a/experiments/lcheck-fixture/site/assets/style.css b/experiments/lcheck-fixture/site/assets/style.css
new file mode 100644
index 00000000..6f5b686d
--- /dev/null
+++ b/experiments/lcheck-fixture/site/assets/style.css
@@ -0,0 +1 @@
+body { color: black; }
diff --git a/experiments/lcheck-fixture/site/good-dir-noindex/other.html b/experiments/lcheck-fixture/site/good-dir-noindex/other.html
new file mode 100644
index 00000000..f6486613
--- /dev/null
+++ b/experiments/lcheck-fixture/site/good-dir-noindex/other.html
@@ -0,0 +1,2 @@
+<!DOCTYPE html>
+<title>no index here</title>
diff --git a/experiments/lcheck-fixture/site/good-dir/index.html b/experiments/lcheck-fixture/site/good-dir/index.html
new file mode 100644
index 00000000..40c4b3a1
--- /dev/null
+++ b/experiments/lcheck-fixture/site/good-dir/index.html
@@ -0,0 +1,3 @@
+<!DOCTYPE html>
+<title>dir index</title>
+<h2 id="dir-anchor">Dir Anchor</h2>
diff --git a/experiments/lcheck-fixture/site/good-fallback.html b/experiments/lcheck-fixture/site/good-fallback.html
new file mode 100644
index 00000000..6c656bbc
--- /dev/null
+++ b/experiments/lcheck-fixture/site/good-fallback.html
@@ -0,0 +1,2 @@
+<!DOCTYPE html>
+<title>fallback</title>
diff --git a/experiments/lcheck-fixture/site/good-fragments.html b/experiments/lcheck-fixture/site/good-fragments.html
new file mode 100644
index 00000000..1fd6c7d4
--- /dev/null
+++ b/experiments/lcheck-fixture/site/good-fragments.html
@@ -0,0 +1,4 @@
+<!DOCTYPE html>
+<title>frag</title>
+<h2 id="known">Known</h2>
+<a name="legacy-anchor">legacy</a>
diff --git a/experiments/lcheck-fixture/site/good.html b/experiments/lcheck-fixture/site/good.html
new file mode 100644
index 00000000..6312e989
--- /dev/null
+++ b/experiments/lcheck-fixture/site/good.html
@@ -0,0 +1,3 @@
+<!DOCTYPE html>
+<title>good</title>
+<h1 id="top">good</h1>
diff --git a/experiments/lcheck-fixture/site/index.html b/experiments/lcheck-fixture/site/index.html
new file mode 100644
index 00000000..fd7f87e2
--- /dev/null
+++ b/experiments/lcheck-fixture/site/index.html
@@ -0,0 +1,63 @@
+<!DOCTYPE html>
+<html>
+<head>
+<title>fixture root</title>
+<link rel="stylesheet" href="assets/style.css">
+<link rel="stylesheet" href="assets/MISSING.css">
+<script src="assets/script.js"></script>
+<script src="assets/MISSING.js"></script>
+</head>
+<body>
+<h1 id="top">Fixture</h1>
+
+<h2>Plain hrefs</h2>
+<a href="good.html">OK file</a>
+<a href="MISSING.html">BROKEN: missing file</a>
+
+<h2>Fallback extension (only good-fallback.html exists)</h2>
+<a href="good-fallback">OK via fallback .html</a>
+<a href="missing-fallback">BROKEN: no missing-fallback.html</a>
+
+<h2>Trailing slash forces directory resolution</h2>
+<a href="good.html/">BROKEN: good.html is a file, not a dir</a>
+<a href="good-fallback/">BROKEN: good-fallback resolves to .html via fallback, not via dir</a>
+
+<h2>Directory with index.html (both forms should be OK)</h2>
+<a href="good-dir/">OK dir with index</a>
+<a href="good-dir">OK dir with index (no slash)</a>
+
+<h2>Directory without index.html, but `.` in --index-files</h2>
+<a href="good-dir-noindex/">OK: accepts dir itself</a>
+<a href="good-dir-noindex">OK: same, via dir fallback</a>
+
+<h2>Missing dirs</h2>
+<a href="missing-dir/">BROKEN: dir does not exist</a>
+<a href="missing-dir">BROKEN: not a file, not a dir, no fallback</a>
+
+<h2>Fragments</h2>
+<a href="#top">OK: same-page fragment</a>
+<a href="#bogus">BROKEN: same-page bad fragment</a>
+<a href="good-fragments.html#known">OK: cross-page known fragment</a>
+<a href="good-fragments.html#bogus">BROKEN: cross-page bad fragment</a>
+<a href="good-dir/#dir-anchor">OK: dir-link with fragment</a>
+<a href="good-dir/#bogus">BROKEN: dir-link bad fragment</a>
+
+<h2>Relative and absolute paths</h2>
+<a href="subdir/nested.html">OK relative subdir</a>
+<a href="/good.html">OK absolute via root-dir</a>
+<a href="/MISSING.html">BROKEN absolute</a>
+
+<h2>External and skipped schemes</h2>
+<a href="https://example.com">SKIP: http</a>
+<a href="mailto:nobody@example.com">SKIP: mailto</a>
+<a href="javascript:void(0)">SKIP: js</a>
+<a href="tel:+1234">SKIP: tel</a>
+
+<h2>Images</h2>
+<img src="subdir/image.png" alt="OK">
+<img src="subdir/MISSING.png" alt="BROKEN">
+
+<h2>Image srcset</h2>
+<img srcset="subdir/image.png 1x, subdir/MISSING.png 2x" alt="srcset mixed">
+</body>
+</html>
diff --git a/experiments/lcheck-fixture/site/subdir/image.png b/experiments/lcheck-fixture/site/subdir/image.png
new file mode 100644
index 00000000..7838a96f
--- /dev/null
+++ b/experiments/lcheck-fixture/site/subdir/image.png
@@ -0,0 +1 @@
+fake png
\ No newline at end of file
diff --git a/experiments/lcheck-fixture/site/subdir/nested.html b/experiments/lcheck-fixture/site/subdir/nested.html
new file mode 100644
index 00000000..1c22b823
--- /dev/null
+++ b/experiments/lcheck-fixture/site/subdir/nested.html
@@ -0,0 +1,4 @@
+<!DOCTYPE html>
+<title>nested</title>
+<a href="../good.html">up and over</a>
+<a href="../MISSING-from-subdir.html">BROKEN: missing from subdir</a>
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 00000000..4eb0354a
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1 @@
+selectolax>=0.4
diff --git a/scripts/check_links.py b/scripts/check_links.py
new file mode 100644
index 00000000..cea09f4f
--- /dev/null
+++ b/scripts/check_links.py
@@ -0,0 +1,401 @@
+"""
+Offline link checker for static sites.
+
+CLI mirrors the subset of lychee flags used by docs/check.bat, so that an
+invocation like
+
+    python scripts/check_links.py --offline --include-fragments
+        --fallback-extensions html --index-files "index.html,."
+        --root-dir docs/_site docs/_site
+
+produces the same correctness verdict as the equivalent lychee call (only
+faster and a bit stricter -- see "Differences from lychee" below).
+
+Why this exists: lychee's offline pipeline funnels every link occurrence
+through an async channel before its dedup cache short-circuits the work.
+On this site (~733k occurrences, ~12k unique targets) that fixed-per-
+occurrence overhead is ~50s on Windows. This script dedupes (target, frag)
+up front, so the filesystem and fragment checks run once per unique target.
+
+Online (network) link checking is not implemented. --offline is therefore
+required; the script exits non-zero if it is absent.
+
+Differences from lychee (correctness):
+  * Trailing slash on a file-shaped URL ('foo.html/') is reported broken,
+    where lychee normalises and accepts. Catches authoring mistakes.
+  * <script src> URLs are checked. Lychee 0.24.1 silently skips them.
+
+Differences from lychee (output): no per-link line numbers in error
+messages -- selectolax doesn't expose source positions.
+"""
+
+import argparse
+import os
+import sys
+import time
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from urllib.parse import unquote, urlparse
+
+from selectolax.parser import HTMLParser
+
+# (selector, attribute_name) pairs. We can't use a single multi-selector
+# query because some elements expose links under non-href/src attributes
+# (cite, action, data, srcset, ...). Lychee covers a similar set in
+# lychee-lib/src/extract/html/html5gum.rs.
+LINK_ATTRS = [
+    ("a[href]", "href"),
+    ("area[href]", "href"),
+    ("base[href]", "href"),
+    ("link[href]", "href"),
+    ("img[src]", "src"),
+    ("img[longdesc]", "longdesc"),
+    ("img[srcset]", "srcset"),
+    ("script[src]", "src"),
+    ("iframe[src]", "src"),
+    ("frame[src]", "src"),
+    ("embed[src]", "src"),
+    ("source[src]", "src"),
+    ("source[srcset]", "srcset"),
+    ("audio[src]", "src"),
+    ("video[src]", "src"),
+    ("video[poster]", "poster"),
+    ("track[src]", "src"),
+    ("input[src]", "src"),
+    ("input[formaction]", "formaction"),
+    ("button[formaction]", "formaction"),
+    ("form[action]", "action"),
+    ("object[data]", "data"),
+    ("blockquote[cite]", "cite"),
+    ("q[cite]", "cite"),
+    ("del[cite]", "cite"),
+    ("ins[cite]", "cite"),
+]
+
+SRCSET_ATTRS = {"srcset"}
+
+
+def _split_srcset(value):
+    # srcset is `URL [descriptor], URL [descriptor], ...`. Descriptors
+    # cannot contain commas, so a comma split is safe; each part's first
+    # whitespace-separated token is the URL.
+    for part in value.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        url = part.split(None, 1)[0]
+        if url:
+            yield url
+
+
+def extract_links(html_path):
+    data = html_path.read_bytes()
+    tree = HTMLParser(data)
+    out = []
+    for selector, attr in LINK_ATTRS:
+        for node in tree.css(selector):
+            v = node.attributes.get(attr)
+            if not v:
+                continue
+            if attr in SRCSET_ATTRS:
+                out.extend(_split_srcset(v))
+            else:
+                out.append(v)
+    return out
+
+
+def extract_fragment_ids(html_path):
+    data = html_path.read_bytes()
+    tree = HTMLParser(data)
+    ids = set()
+    for node in tree.css("[id]"):
+        v = node.attributes.get("id")
+        if v:
+            ids.add(v)
+    for node in tree.css("a[name]"):
+        v = node.attributes.get("name")
+        if v:
+            ids.add(v)
+    return ids
+
+
+def resolve(href, source_dir_str, source_str, root_str):
+    """Lexically resolve href -> (normalized_target_str, is_dir_link, fragment).
+    Returns None for schemes/netlocs we skip. Uses only string ops — no
+    filesystem syscalls (Path.resolve is ~110us per call on Windows).
+
+    is_dir_link captures whether the URL ended in '/' before normalization.
+    os.path.normpath strips trailing slashes, but the distinction matters
+    for resolution: 'foo/' must resolve as a directory (try index files),
+    while 'foo' falls through to fallback extensions ('foo.html') if no
+    file/dir 'foo' exists.
+    """
+    if "#" in href:
+        path_part, frag = href.split("#", 1)
+    else:
+        path_part, frag = href, None
+    if not path_part:
+        return source_str, False, frag
+
+    if ":" in path_part[:16] or path_part.startswith("//"):
+        parsed = urlparse(path_part)
+        if parsed.scheme or parsed.netloc:
+            return None
+        path_str = parsed.path
+    else:
+        path_str = path_part
+
+    if "%" in path_str:
+        path_str = unquote(path_str)
+
+    is_dir_link = path_str.endswith("/") or path_str.endswith("/.")
+
+    if path_str.startswith("/"):
+        target = os.path.normpath(os.path.join(root_str, path_str.lstrip("/")))
+    else:
+        target = os.path.normpath(os.path.join(source_dir_str, path_str))
+    return target, is_dir_link, frag
+
+
+def check_path(target_str, is_dir_link, fallback_exts, index_files):
+    """Mirror lychee --fallback-extensions / --index-files semantics.
+
+    A trailing-slash URL ('foo/') must resolve as a directory: try each
+    index_file in order, with '.' meaning 'accept the directory itself'.
+    Fallback extensions never apply to dir-shaped links.
+
+    A non-slash URL ('foo') tries the path as a file first, then as a dir
+    (same index-file logic), then falls back to fallback extensions.
+    """
+    target = Path(target_str)
+    if is_dir_link:
+        if not target.is_dir():
+            return None
+        for idx in index_files:
+            if idx == ".":
+                return target
+            cand = target / idx
+            if cand.is_file():
+                return cand
+        return None
+    if target.is_file():
+        return target
+    if target.is_dir():
+        for idx in index_files:
+            if idx == ".":
+                return target
+            cand = target / idx
+            if cand.is_file():
+                return cand
+        return None
+    for ext in fallback_exts:
+        cand = Path(target_str + "." + ext)
+        if cand.is_file():
+            return cand
+    return None
+
+
+def _build_parser():
+    ap = argparse.ArgumentParser(
+        prog="check_links.py",
+        description=(
+            "Offline link checker. CLI mirrors the subset of lychee flags "
+            "used by check.bat. Only offline checking is implemented; "
+            "--offline is required."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    ap.add_argument(
+        "--offline", action="store_true",
+        help=(
+            "REQUIRED. Skip network checks (the only mode supported). "
+            "This script exits non-zero if the flag is absent."
+        ),
+    )
+    ap.add_argument(
+        "--include-fragments", action="store_true",
+        help=(
+            "Verify URL fragments (#anchor) against id/name attributes in "
+            "the target HTML. Off by default to match lychee."
+        ),
+    )
+    ap.add_argument(
+        "--fallback-extensions", default="", metavar="EXTS",
+        help=(
+            "Comma-separated extensions to try if a path does not resolve "
+            "as-is (e.g. 'html'). Empty by default."
+        ),
+    )
+    ap.add_argument(
+        "--index-files", default="", metavar="FILES",
+        help=(
+            "Comma-separated index file names to try when a path resolves "
+            "to a directory. Use '.' to accept the directory itself when "
+            "no index file matches. Empty by default."
+        ),
+    )
+    ap.add_argument(
+        "--root-dir", type=Path, metavar="DIR",
+        help=(
+            "Root directory for absolute URL paths (e.g. '/foo'). "
+            "If absent, absolute URLs cannot be resolved and are reported "
+            "as broken."
+        ),
+    )
+    ap.add_argument(
+        "--threads", type=int, default=os.cpu_count() or 4, metavar="N",
+        help="Worker threads for HTML parsing. Default: CPU count.",
+    )
+    ap.add_argument(
+        "-v", "--verbose", action="store_true",
+        help="Print per-stage timing breakdown.",
+    )
+    ap.add_argument(
+        "inputs", nargs="+", type=Path,
+        help=(
+            "Files or directories to scan. Directories are searched "
+            "recursively for *.html."
+        ),
+    )
+    return ap
+
+
+def _collect_html_files(inputs):
+    out = []
+    for inp in inputs:
+        if inp.is_file():
+            out.append(inp)
+        elif inp.is_dir():
+            out.extend(inp.rglob("*.html"))
+        else:
+            print(f"warning: input not found: {inp}", file=sys.stderr)
+    return out
+
+
+def main():
+    ap = _build_parser()
+    # parse_known_args so extra lychee flags passed via check.bat's %*
+    # don't break us. Unknown flags are surfaced as a warning.
+    args, extra = ap.parse_known_args()
+    if extra:
+        print(
+            f"warning: ignoring unrecognised arguments: {' '.join(extra)}",
+            file=sys.stderr,
+        )
+
+    if not args.offline:
+        ap.error(
+            "--offline is required. Online (network) checking is not "
+            "implemented by this tool; use lychee for that."
+        )
+
+    root_str = str(args.root_dir.resolve()) if args.root_dir else ""
+    fallback_exts = [e for e in args.fallback_extensions.split(",") if e]
+    index_files = [e for e in args.index_files.split(",") if e]
+
+    t0 = time.perf_counter()
+    html_files = _collect_html_files(args.inputs)
+    t_walk = time.perf_counter()
+
+    # Per-file: extract once, then group hrefs by (source_dir, href) so we
+    # resolve each unique combination exactly once. The same nav/footer
+    # links repeat across hundreds of pages from the same directory.
+    occurrences = []  # (source_path, source_dir_str, href)
+    with ThreadPoolExecutor(max_workers=args.threads) as ex:
+        for src, hrefs in zip(html_files, ex.map(extract_links, html_files)):
+            src_dir = str(src.parent)
+            src_str = str(src)
+            for h in hrefs:
+                occurrences.append((src_str, src_dir, h))
+    t_extract = time.perf_counter()
+
+    # Memoize resolution by (source_dir, href). Each unique (dir, href)
+    # resolves identically regardless of which file in that dir found it.
+    resolution_cache = {}
+    unique_checks = {}
+    for src_str, src_dir, href in occurrences:
+        rk = (src_dir, href)
+        r = resolution_cache.get(rk, ...)
+        if r is ...:
+            r = resolve(href, src_dir, src_str, root_str)
+            resolution_cache[rk] = r
+        if r is None:
+            continue
+        target, is_dir, frag = r
+        # Include is_dir in the key: 'foo' and 'foo/' resolve via
+        # different rules even after normpath collapses them.
+        key = (target, is_dir, frag)
+        unique_checks.setdefault(key, []).append((src_str, href))
+    t_resolve = time.perf_counter()
+
+    path_keys = sorted({(t, d) for (t, d, _) in unique_checks})
+    target_resolution = {}
+    for (t, d) in path_keys:
+        target_resolution[(t, d)] = check_path(t, d, fallback_exts, index_files)
+    t_check_paths = time.perf_counter()
+
+    files_for_fragments = sorted({
+        target_resolution[(t, d)] for (t, d, f) in unique_checks
+        if f and target_resolution.get((t, d))
+    })
+    fragment_cache = {}
+    if args.include_fragments and files_for_fragments:
+        with ThreadPoolExecutor(max_workers=args.threads) as ex:
+            for f, ids in zip(files_for_fragments,
+                              ex.map(extract_fragment_ids, files_for_fragments)):
+                fragment_cache[f] = ids
+    t_fragments = time.perf_counter()
+
+    broken = []
+    for (target_str, is_dir, frag), sources in unique_checks.items():
+        resolved = target_resolution.get((target_str, is_dir))
+        if resolved is None:
+            for src_str, href in sources:
+                broken.append((src_str, href, "target not found"))
+            continue
+        if frag and args.include_fragments:
+            ids = fragment_cache.get(resolved, set())
+            if frag not in ids:
+                for src_str, href in sources:
+                    broken.append((src_str, href, f"fragment #{frag} not found"))
+    t_done = time.perf_counter()
+
+    total = len(occurrences)
+    unique = len(unique_checks)
+    errors = len(broken)
+    ok = unique - errors
+
+    if broken:
+        # Group by source file, lychee-style.
+        by_source = {}
+        for src_str, href, reason in broken:
+            by_source.setdefault(src_str, []).append((href, reason))
+        for src_str in sorted(by_source):
+            print(f"\n[{src_str}]:")
+            for href, reason in by_source[src_str]:
+                print(f"  ERROR  {href} -- {reason}")
+        print()
+
+    elapsed = t_done - t0
+    print(
+        f"Checked {total} links ({unique} unique) in {elapsed:.3f}s "
+        f"-- {ok} OK, {errors} errors"
+    )
+
+    if args.verbose:
+        print()
+        print(f"  Files scanned:        {len(html_files)}")
+        print(f"  Fragment targets:     {len(files_for_fragments)}")
+        print(f"  Walk:        {t_walk - t0:.3f}s")
+        print(f"  Extract:     {t_extract - t_walk:.3f}s")
+        print(f"  Resolve:     {t_resolve - t_extract:.3f}s")
+        print(f"  Check paths: {t_check_paths - t_resolve:.3f}s")
+        print(f"  Fragments:   {t_fragments - t_check_paths:.3f}s")
+        print(f"  Report:      {t_done - t_fragments:.3f}s")
+
+    if broken:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

From 75b68f9f57787aac4729d0a01186eb4aec578782 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 17 May 2026 20:11:00 +0200
Subject: [PATCH 2/3] Use the new link checker in the CI for the offline site.

---
 .github/workflows/checks.yml          | 17 ++++++++++--
 .github/workflows/jekyll-gh-pages.yml | 40 ++++++++++++++++-----------
 2 files changed, 39 insertions(+), 18 deletions(-)

diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml
index 116a692b..b66f2ad3 100644
--- a/.github/workflows/checks.yml
+++ b/.github/workflows/checks.yml
@@ -35,7 +35,7 @@ jobs:
       - name: Build with Jekyll
         run: bundle exec jekyll build
         working-directory: ./docs
-      - name: Run Lychee
+      - name: Check online links (lychee)
         uses: lycheeverse/lychee-action@v2
         with:
           args: >-
@@ -45,4 +45,17 @@ jobs:
             --root-dir ${{ github.workspace }}/docs/_site
             ./_site
           workingDirectory: ./docs
-          fail: true
\ No newline at end of file
+          fail: true
+      - name: Set up Python for offline link check
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+      - name: Install Python deps
+        run: pip install -r requirements.txt
+      - name: Check offline links (check_links.py)
+        run: >-
+          python scripts/check_links.py
+          --offline --include-fragments
+          --index-files index.html
+          --root-dir docs/_site-offline
+          docs/_site-offline
\ No newline at end of file
diff --git a/.github/workflows/jekyll-gh-pages.yml b/.github/workflows/jekyll-gh-pages.yml
index f0e35a02..e87144a7 100644
--- a/.github/workflows/jekyll-gh-pages.yml
+++ b/.github/workflows/jekyll-gh-pages.yml
@@ -57,7 +57,7 @@ jobs:
         env:
           JEKYLL_ENV: production
           PAGES_REPO_NWO: "${{ github.repository }}"
-      - name: Run Lychee against the online tree
+      - name: Check online links (lychee)
         uses: lycheeverse/lychee-action@v2
         with:
           # --remap matches the fully-resolved file URI (not the raw href), so the pattern
@@ -68,6 +68,11 @@ jobs:
           # `--fallback-extensions html` mirrors what GitHub Pages does at request time:
           # an extensionless URL like `/FAQ` is served as `/FAQ.html`. Without the flag
           # lychee would flag every pretty permalink on the site.
+          #
+          # Lychee, not the Python checker, handles the online tree here because the
+          # `--remap` flag isn't implemented by scripts/check_links.py; the offline tree
+          # below has all baseurl prefixes already stripped by the offlinify plugin and
+          # so doesn't need it.
           args: >-
             --offline --include-fragments
             --fallback-extensions html
@@ -77,22 +82,25 @@ jobs:
             ./_site
           workingDirectory: ./docs
           fail: true
-      - name: Run Lychee against the offline tree
-        uses: lycheeverse/lychee-action@v2
+      - name: Set up Python for offline link check
+        uses: actions/setup-python@v5
         with:
-          # Strict check on `_site-offline/`: every link must resolve to an actual file
-          # under `file://`, with no extension fallback. Catches relative links in
-          # markdown sources that point at a permalink that doesn't match the rendered
-          # filename (e.g. `[Foo](Foo/)` when Jekyll wrote `Foo.html`, not
-          # `Foo/index.html`) -- the kind of breakage the online check above hides
-          # behind `--fallback-extensions html`.
-          args: >-
-            --offline --include-fragments
-            --index-files 'index.html'
-            --root-dir ${{ github.workspace }}/docs/_site-offline
-            ./_site-offline
-          workingDirectory: ./docs
-          fail: true
+          python-version: '3.14'
+      - name: Install Python deps
+        run: pip install -r requirements.txt
+      - name: Check offline links (check_links.py)
+        # Strict check on `_site-offline/`: every link must resolve to an actual file
+        # under `file://`, with no extension fallback. Catches relative links in
+        # markdown sources that point at a permalink that doesn't match the rendered
+        # filename (e.g. `[Foo](Foo/)` when Jekyll wrote `Foo.html`, not
+        # `Foo/index.html`) -- the kind of breakage the online check above hides
+        # behind `--fallback-extensions html`.
+        run: >-
+          python scripts/check_links.py
+          --offline --include-fragments
+          --index-files index.html
+          --root-dir docs/_site-offline
+          docs/_site-offline
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v5
         with:

From a3fdc46b3520e1e8046bdcbcfe01eefbb6b6f4eb Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 17 May 2026 20:35:54 +0200
Subject: [PATCH 3/3] Run the check for offline live links in the CI.

---
 .github/workflows/checks.yml                  | 11 ++++++++++-
 .github/workflows/jekyll-gh-pages.yml         |  9 +++++++++
 .../Documentation Development.md              |  2 +-
 docs/_plugins/offlinify.md                    | 19 +++++++++++--------
 4 files changed, 31 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml
index b66f2ad3..30f83ff2 100644
--- a/.github/workflows/checks.yml
+++ b/.github/workflows/checks.yml
@@ -58,4 +58,13 @@ jobs:
           --offline --include-fragments
           --index-files index.html
           --root-dir docs/_site-offline
-          docs/_site-offline
\ No newline at end of file
+          docs/_site-offline
+      - name: Check for surviving live-site links in offline tree
+        # Flags any https://docs.twinbasic.com/<path> reference left in
+        # _site-offline/ HTML outside <code>/<pre> blocks. After offlinify
+        # strips the jekyll-seo-tag block, anything surviving is a source
+        # link that points at the live site instead of using a relative or
+        # /tB/... permalink that resolves locally. The bare root URL
+        # (https://docs.twinbasic.com[/]) is exempt -- intentional "go to
+        # the live site" links are allowed.
+        run: python scripts/check_offline_live_links.py
\ No newline at end of file
diff --git a/.github/workflows/jekyll-gh-pages.yml b/.github/workflows/jekyll-gh-pages.yml
index e87144a7..346d02ad 100644
--- a/.github/workflows/jekyll-gh-pages.yml
+++ b/.github/workflows/jekyll-gh-pages.yml
@@ -101,6 +101,15 @@ jobs:
           --index-files index.html
           --root-dir docs/_site-offline
           docs/_site-offline
+      - name: Check for surviving live-site links in offline tree
+        # Flags any https://docs.twinbasic.com/<path> reference left in
+        # _site-offline/ HTML outside <code>/<pre> blocks. After offlinify
+        # strips the jekyll-seo-tag block, anything surviving is a source
+        # link that points at the live site instead of using a relative or
+        # /tB/... permalink that resolves locally. The bare root URL
+        # (https://docs.twinbasic.com[/]) is exempt -- intentional "go to
+        # the live site" links are allowed.
+        run: python scripts/check_offline_live_links.py
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v5
         with:
diff --git a/docs/Miscellaneous/Documentation Development.md b/docs/Miscellaneous/Documentation Development.md
index 6105eac1..9ea54887 100644
--- a/docs/Miscellaneous/Documentation Development.md	
+++ b/docs/Miscellaneous/Documentation Development.md	
@@ -201,7 +201,7 @@ To check that none of the internal links in the most recent documentation build
 
     check.bat
 
-This runs three checks: [Lychee](https://github.com/lycheeverse/lychee) in offline mode against `_site/` (the live tree), the same against `_site-offline/` (the file://-browsable mirror), and a small Python pass over `_site-offline/` that flags any surviving `https://docs.twinbasic.com/<path>` link --- the offline mirror should not navigate back to the live docs site.
+This runs three checks: `scripts/check_links.py` against `_site/` (the live tree, in offline mode), the same against `_site-offline/` (the file://-browsable mirror), and `scripts/check_offline_live_links.py` over `_site-offline/` that flags any surviving `https://docs.twinbasic.com/<path>` link --- the offline mirror should not navigate back to the live docs site. The same three checks run in CI on every pull request and on every push to `staging`.
 
 ### Building and Local Serving
 
diff --git a/docs/_plugins/offlinify.md b/docs/_plugins/offlinify.md
index 979afe7b..549a8db9 100644
--- a/docs/_plugins/offlinify.md
+++ b/docs/_plugins/offlinify.md
@@ -300,22 +300,25 @@ The offline build touches the following files:
 | `docs/_config.yml` | `also_build_offline: true` (default-on) and `exclude: [_site-offline]` (keeps Jekyll's watcher from rebuilding on the plugin's own output). |
 | `docs/build.bat` | Plain `bundle exec jekyll build` — produces `_site/`, `_site-offline/`, and (via `pdfify.rb`) `_site-pdf/` in one run. |
 | `docs/serve.bat` | `bundle exec jekyll serve` — watcher-friendly thanks to the exclude. |
-| `docs/check.bat` | Local link check (dev-side only; CI runs the two lychee passes directly). Three steps: lychee permissive on `_site/`, lychee strict on `_site-offline/`, and `scripts/check_offline_live_links.py` against `_site-offline/`. Exits non-zero on any failure. |
-| `scripts/check_offline_live_links.py` | Flags any `https://docs.twinbasic.com/<path>` reference that survived offlinify in `_site-offline/` HTML, outside `<code>` / `<pre>` blocks. Skips the bare root (`https://docs.twinbasic.com[/]`) since intentional "go to the live site" links are allowed. Caught locally by `check.bat`; not wired into CI. |
+| `docs/check.bat` | Local link check (CI runs the same three passes via the workflows). Three steps: `scripts/check_links.py` permissive on `_site/`, `scripts/check_links.py` strict on `_site-offline/`, and `scripts/check_offline_live_links.py` against `_site-offline/`. Exits non-zero on any failure. |
+| `scripts/check_offline_live_links.py` | Flags any `https://docs.twinbasic.com/<path>` reference that survived offlinify in `_site-offline/` HTML, outside `<code>` / `<pre>` blocks. Skips the bare root (`https://docs.twinbasic.com[/]`) since intentional "go to the live site" links are allowed. Run by `check.bat` locally and by both CI workflows after the offline link check. |
 | `docs/.gitignore` | `_site`, `_site-offline`, and `_site-pdf` all excluded from git. |
-| `.github/workflows/jekyll-gh-pages.yml` | CI workflow. Builds, runs lychee against both trees, deploys to Pages, and (on manual dispatch) packages `_site-offline/` as a release artifact. |
+| `.github/workflows/jekyll-gh-pages.yml` | Deploy workflow (push to `staging`, manual dispatch). Builds, runs lychee against `_site/`, runs `scripts/check_links.py` against `_site-offline/`, runs `scripts/check_offline_live_links.py` against `_site-offline/`, deploys to Pages, and (on manual dispatch) packages `_site-offline/` as a release artifact. |
+| `.github/workflows/checks.yml` | PR-gating workflow (pull-request to `main`, manual dispatch). Same three link-check steps as the deploy workflow; no deploy or release. |
 
 ## CI integration
 
 `bundle exec jekyll build` in CI passes `--baseurl "${{ steps.pages.outputs.base_path }}"` from `actions/configure-pages`. For a Pages site with a custom domain (CNAME), base_path is empty. For a project page without a custom domain, it's `/repo-name`. Offlinify handles both cases — `normalize_baseurl` in `setup` produces the right prefix to strip.
 
-The workflow has two lychee steps after the build:
+The workflow has three link-check steps after the build:
 
-1. **Against `_site/`**, with `--fallback-extensions html` and a `--remap` that strips the base_path prefix. This mirrors what GitHub Pages does at request time — extensionless URLs like `/FAQ` get served as `/FAQ.html`. Without `--fallback-extensions html`, every pretty permalink would appear broken in this check.
+1. **Lychee against `_site/`**, with `--fallback-extensions html` and a `--remap` that strips the base_path prefix. This mirrors what GitHub Pages does at request time — extensionless URLs like `/FAQ` get served as `/FAQ.html`. Without `--fallback-extensions html`, every pretty permalink would appear broken in this check. Lychee (not `scripts/check_links.py`) handles the online tree because `--remap` isn't implemented in the Python checker; the offline tree below has all baseurl prefixes already stripped by offlinify and doesn't need it.
 
-2. **Against `_site-offline/`**, strict — no extension fallback (`--index-files 'index.html'` only; the online check also accepts the bare directory via `,.`). Every link must resolve to a real file as written. This catches relative links in markdown sources whose permalink shape doesn't match the rendered filename (e.g. `[Foo](Foo/)` when Jekyll wrote `Foo.html`, not `Foo/index.html`) — the kind of breakage the online check above hides behind both the fallback and the bare-directory acceptance.
+2. **`scripts/check_links.py` against `_site-offline/`**, strict — no extension fallback (`--index-files index.html` only; the online check also accepts the bare directory via `,.`). Every link must resolve to a real file as written. This catches relative links in markdown sources whose permalink shape doesn't match the rendered filename (e.g. `[Foo](Foo/)` when Jekyll wrote `Foo.html`, not `Foo/index.html`) — the kind of breakage the online check above hides behind both the fallback and the bare-directory acceptance. The Python checker is roughly 25× faster than lychee on this workload and a bit stricter (catches missing `<script src>` targets and trailing slashes on file-shaped URLs).
 
-Both checks set `fail: true`. Any unresolved link fails the build, blocks the Pages deploy, and blocks the release upload. After both lychee runs succeed and Pages is deployed, the release job (gated to manual dispatch only) downloads the offline-site workflow artifact, computes a tag like `docs-YYYY-MM-DD-HHMM` (UTC), and creates a GitHub release with `twinbasic-docs-offline.zip` attached via `softprops/action-gh-release@v2`.
+3. **`scripts/check_offline_live_links.py` against `_site-offline/`**, flagging any surviving `https://docs.twinbasic.com/<path>` reference outside `<code>` / `<pre>` blocks (the bare root is exempt — see [Failure modes: Surviving live-site links](#failure-modes)).
+
+All three steps fail the build on the first non-zero exit, blocking the Pages deploy and the release upload. After they succeed and Pages is deployed, the release job (gated to manual dispatch only) downloads the offline-site workflow artifact, computes a tag like `docs-YYYY-MM-DD-HHMM` (UTC), and creates a GitHub release with `twinbasic-docs-offline.zip` attached via `softprops/action-gh-release@v2`.
 
 ## Failure modes
 
@@ -331,7 +334,7 @@ The plugin surfaces several conditions in its summary log lines:
 
 - **`_site-offline/` triggering `jekyll serve` rebuilds.** Was a problem; now handled by two things in combination: `exclude: [_site-offline]` in `_config.yml`, and the "clean contents but keep the directory" trick in the wipe step (which keeps all watcher events under `_site-offline/...` where the exclude matches).
 
-- **Surviving live-site links.** The [SEO block stripping](#seo-block-stripping) pass removes the bulk of `https://docs.twinbasic.com` references each page contains (canonical link, OpenGraph URL, JSON-LD `url`). Anything left in `_site-offline/` is a source link that points at the live docs site -- usually a markdown author writing `https://docs.twinbasic.com/<path>` instead of a relative link or `/tB/...` permalink, which would silently navigate the offline reader back online. `scripts/check_offline_live_links.py` (run by `check.bat` after the offline lychee pass) flags these locally; the bare root `https://docs.twinbasic.com[/]` is exempt since intentional "go to the live site" links are allowed. CI does not run this check.
+- **Surviving live-site links.** The [SEO block stripping](#seo-block-stripping) pass removes the bulk of `https://docs.twinbasic.com` references each page contains (canonical link, OpenGraph URL, JSON-LD `url`). Anything left in `_site-offline/` is a source link that points at the live docs site -- usually a markdown author writing `https://docs.twinbasic.com/<path>` instead of a relative link or `/tB/...` permalink, which would silently navigate the offline reader back online. `scripts/check_offline_live_links.py` flags these; the bare root `https://docs.twinbasic.com[/]` is exempt since intentional "go to the live site" links are allowed. Run locally by `check.bat` and in CI by both workflows after the offline link check.
 
 ## Performance