From cddeade38b700eeca58cdc3329df62c36ab20cab Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 17 May 2026 16:25:34 +0200
Subject: [PATCH 1/6] Add timing information to book-href-rewriter and pdflify.

---
 docs/_plugins/book-href-rewrite.rb | 5 +++++
 docs/_plugins/pdfify.rb            | 5 +++++
 2 files changed, 10 insertions(+)

diff --git a/docs/_plugins/book-href-rewrite.rb b/docs/_plugins/book-href-rewrite.rb
index 963ff87..d0b7486 100644
--- a/docs/_plugins/book-href-rewrite.rb
+++ b/docs/_plugins/book-href-rewrite.rb
@@ -228,6 +228,8 @@ def self.process(page)
     return if parent_map.empty?
     landing_anchors = build_landing_anchors(site)
 
+    start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
     rewritten = 0
     landings_stripped = 0
     page.output = page.output.gsub(/(<article[^>]*id="(ch-[^"]+)"[^>]*>)(.*?)(<\/article>)/m) do
@@ -254,6 +256,9 @@ def self.process(page)
       "#{article_open}#{body}#{article_end}"
     end
     Jekyll.logger.info "BookHrefRewrite:", "rewrote #{rewritten} chapter bodies, stripped #{landings_stripped} landing H3s"
+
+    elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(0)
+    Jekyll.logger.info "BookHrefRewrite:", "BookHrefRewriter ran in #{elapsed_ms}ms."
   end
 end
 
diff --git a/docs/_plugins/pdfify.rb b/docs/_plugins/pdfify.rb
index 6e8e0ac..a36777b 100644
--- a/docs/_plugins/pdfify.rb
+++ b/docs/_plugins/pdfify.rb
@@ -88,6 +88,8 @@ def self.run(site, source_root, dest_root)
       return
     end
 
+    start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
     # Wipe the destination tree so previous runs do not leave stale
     # images behind when source pages are deleted or renamed.
     FileUtils.rm_rf(dest)
@@ -132,6 +134,9 @@ def self.run(site, source_root, dest_root)
     book_src.delete
 
     Jekyll.logger.info "Pdfify:", "wrote #{dest_root} -- copied #{copied} file(s) (#{image_paths.size} image(s)#{skipped.zero? ? "" : ", #{skipped} missing"})"
+
+    elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(0)
+    Jekyll.logger.info "Pdfify:", "Pdfifier ran in #{elapsed_ms}ms."
   end
 
   # Walks book.html for relative `<img src=>` URLs and returns the

From 3ff66be99f0f8638b1b86cd2235f89be26f269fb Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 17 May 2026 16:41:07 +0200
Subject: [PATCH 2/6] Speed up offlinify by 4s.

---
 docs/_plugins/offlinify.md |  73 +++++++++----------
 docs/_plugins/offlinify.rb | 140 +++++++++++++++++++------------------
 2 files changed, 110 insertions(+), 103 deletions(-)

diff --git a/docs/_plugins/offlinify.md b/docs/_plugins/offlinify.md
index 49b7785..1d1aac4 100644
--- a/docs/_plugins/offlinify.md
+++ b/docs/_plugins/offlinify.md
@@ -41,7 +41,7 @@ After Jekyll's WRITE phase completes, the hook fires `Offlinify.run(site, src_de
 
 4. **Walk the source tree.** For each file:
    - If the file matches a pattern in `site.config["offline_exclude"]` (see [Exclude list](#exclude-list)): skip the copy so the online `_site/` keeps it and the offline tree doesn't.
-   - `.html`: read once, run three transformation passes in order (absolute-URL rewrite, relative-URL rewrite, search-setup injection), write back if any pass changed content.
+   - `.html`: read once, run two transformation passes in order (combined HTML URL rewrite, search-setup injection), write back if any pass changed content.
    - `.css`: read, run the `url()` rewrite, write back.
    - Anything else (images, fonts, JSON, JS): plain `FileUtils.cp` into the offline tree.
 
@@ -53,11 +53,22 @@ After Jekyll's WRITE phase completes, the hook fires `Offlinify.run(site, src_de
 
 ## Transformation passes
 
-### Pass 1: absolute URL rewriting (HTML)
+### HTML URL rewriting
 
-Regex: `\b(href|src)=(["'])(\/(?!\/)[^"']*)\2` — captures `href` or `src` attribute values that start with a single `/` (not `//`, which is protocol-relative).
+A single combined regex matches both absolute and page-relative URLs in `href`/`src` attributes:
 
-For each match, `compute_relative` does the following:
+`\b(href|src)=(["'])(\/(?!\/)[^"']*|(?![#/]|[a-zA-Z][a-zA-Z0-9+.\-]*:)[^"']+)\2`
+
+The third capture (the URL) has two alternatives:
+
+- **Absolute** (`\/(?!\/)[^"']*`): starts with a single `/`, not `//` (protocol-relative). Produced by `relative_url`. Goes through `compute_relative`.
+- **Page-relative** (`(?![#/]|[a-zA-Z][a-zA-Z0-9+.\-]*:)[^"']+`): does not start with `#` (fragment-only — leave alone), `/` (handled by the first alternative), or a `scheme:` prefix (`http:`, `mailto:`, `tel:`, `javascript:`, etc.). Comes from markdown sources verbatim (`[Description](Attributes#description)`-style); Jekyll passes these through without applying `relative_url`, so they reach the rendered HTML without a baseurl prefix. Goes through `compute_rel_url`.
+
+The two alternatives are disjoint at the start of the URL, so a single `gsub` handles both. Inside the block, dispatch on `raw.start_with?("/")`. (An earlier two-regex design ran two full gsubs and re-scanned the file for code-block ranges between them; combining them halved the per-file regex work — see [Performance](#performance).)
+
+#### Absolute-URL path: `compute_relative`
+
+For each absolute-URL match, the steps are:
 
 1. **Split off query/fragment.** `#section` and `?foo=bar` are preserved verbatim onto the rewritten URL.
 
@@ -96,37 +107,26 @@ descend       = "Tutorials/CustomControls/Form%20Designer.html"
 result        = "../../Tutorials/CustomControls/Form%20Designer.html#section"
 ```
 
-**Code-block skip.** Before the rewrite regex runs, the file's content is scanned once for `<code>…</code>` and `<pre>…</pre>` blocks. The byte ranges of their bodies are passed to the regex callback, which returns the match verbatim when the match offset falls inside any range. The skip has two consequences:
-
-- Example URLs in tutorial code samples (e.g. `<script src="/script.js">` displayed verbatim in a CEF page) are not rewritten and **don't count toward the "unresolved" counter**. The unresolved counter is now a real bug signal: anything it reports is either a broken source link or an upstream-theme change.
-- Rouge's syntax highlighter HTML-escapes `<` and `>` inside code but leaves `"` alone, so `src="/foo"` survives literally inside `<code>` bodies and would otherwise match the absolute-URL regex. The code-block skip is what makes this invisible.
-
-The same skip applies to Pass 2 (relative URLs).
+#### Page-relative-URL path: `compute_rel_url`
 
-### Pass 2: relative URL rewriting (HTML)
-
-Some links come from markdown sources verbatim, e.g. `[Description](Attributes#description)` in `Const.md`. Jekyll passes these through without applying `relative_url`, so they reach the rendered HTML as page-relative URLs (no leading slash) without a baseurl prefix. The absolute-URL regex from Pass 1 doesn't match them — its alternation requires `\/(?!\/)` at the start.
-
-Pass 2 catches them. The regex `\b(href|src)=(["'])((?![#/]|[a-zA-Z][a-zA-Z0-9+.\-]*:)[^"']+)\2` matches attribute values that:
-
-- Do **not** start with `#` (fragment-only, leave alone).
-- Do **not** start with `/` (handled by Pass 1).
-- Do **not** start with `scheme:` (where `scheme` is any valid RFC 3986 scheme: `http:`, `mailto:`, `tel:`, `javascript:`, etc.).
-- Have at least one character.
-
-`compute_rel_url` resolves the match in three steps:
+For each page-relative match (e.g. `Attributes#description` in `Const.html`), the steps are:
 
 1. **Normalise the relative path** against the current page's directory segments. `..` pops the stack, `.` and consecutive slashes are skipped, anything else is pushed. The result is an absolute site path (`/tB/Core/Attributes` for the `Attributes` example, starting from `tB/Core/Const.html`).
 
-2. **Probe the same three candidates** as Pass 1.
+2. **Probe the same three candidates** as the absolute path.
 
 3. **Append the matching suffix to the *original* relative URL.** Crucially, the output is the original raw plus the suffix that worked — not a freshly computed relative path. From the `Attributes#description` example: the path is already correctly relative to the current page (same directory), the only fix needed is `.html`. So `Attributes` → `Attributes.html` and the original `#description` tail is reattached, giving `Attributes.html#description`.
 
 If the original is already correct (e.g. `href="foo.html"` where `foo.html` exists), the probe of `<path>` matches and the suffix is empty — the URL is left untouched and the match doesn't contribute to the "changed" count. If no candidate matches, the URL is left as-is and the unresolved counter is incremented.
 
-Matches inside code-block bodies are skipped here too (see the note above Pass 2's heading).
+#### Code-block skip
+
+Before the rewrite regex runs, the file's content is scanned once for `<code>…</code>` and `<pre>…</pre>` blocks. The byte ranges of their bodies are passed to the regex callback, which returns the match verbatim when the match offset falls inside any range. The skip has two consequences:
+
+- Example URLs in tutorial code samples (e.g. `<script src="/script.js">` displayed verbatim in a CEF page) are not rewritten and **don't count toward the "unresolved" counter**. The unresolved counter is now a real bug signal: anything it reports is either a broken source link or an upstream-theme change.
+- Rouge's syntax highlighter HTML-escapes `<` and `>` inside code but leaves `"` alone, so `src="/foo"` survives literally inside `<code>` bodies and would otherwise match the URL regex. The code-block skip is what makes this invisible.
 
-### Pass 3: search-setup injection (HTML)
+### Search-setup injection (HTML)
 
 Two `<script>` elements are inserted right before the existing `<script src="...just-the-docs.js">` tag in each rendered HTML:
 
@@ -141,13 +141,13 @@ Two `<script>` elements are inserted right before the existing `<script src="...
 
 Both run in source order before `just-the-docs.js`, so the globals are populated before the document-ready callback fires `initSearch()`.
 
-The injection finds the just-the-docs.js script tag via a regex that captures the relative-path prefix in the existing tag's `src` attribute (e.g. `../../assets/js/`). The same prefix is reused for the new `search-data.js` reference. This works because Pass 1 has already converted the just-the-docs.js `src` from root-absolute to page-relative form by the time Pass 3 runs.
+The injection finds the just-the-docs.js script tag via a regex that captures the relative-path prefix in the existing tag's `src` attribute (e.g. `../../assets/js/`). The same prefix is reused for the new `search-data.js` reference. This works because the HTML URL rewriting pass has already converted the just-the-docs.js `src` from root-absolute to page-relative form by the time the injection runs.
 
 ### CSS `url()` rewriting
 
 The just-the-docs theme ships `background-image: url("/favicon.png")` for the site logo. Without rewriting, this would fail under `file://`.
 
-The regex `url\(\s*(["']?)(\/(?!\/)[^"'()\s]*)\1\s*\)` matches `url(...)` references whose URL starts with a single slash, optionally wrapped in quotes. The rewrite uses the same `compute_relative` as Pass 1.
+The regex `url\(\s*(["']?)(\/(?!\/)[^"'()\s]*)\1\s*\)` matches `url(...)` references whose URL starts with a single slash, optionally wrapped in quotes. The rewrite uses the same `compute_relative` as the HTML absolute-URL path.
 
 In the CSS file the source dir is `_site-offline/assets/css/` so the rewrite emits `url("../../favicon.png")`.
 
@@ -231,7 +231,7 @@ Three caches keep the per-match work to a single Hash lookup once warmed up:
 
 3. **`result_cache`** (`Hash` of `"#{file_dir}\x00#{raw}"` → `final_rel_url` or `nil`). The big win. Subsumes step 1 (raw → site_path) and step 2 (site_path → page-relative URL) so each unique `(file_dir, raw)` pair is computed exactly once across the build. Every page shares its nav and aux-nav with every other page — those links resolve once on the first page and hit cache on every subsequent page. Without this cache the offlinify pass takes ~7× longer.
 
-The cache is shared between the absolute-URL pass (Pass 1) and the relative-URL pass (Pass 2) — the `raw` shapes are disjoint (absolute starts with `/`, relative doesn't), so there's no collision. The `\x00` separator between `file_dir` and `raw` prevents path-name collisions inside the cache key.
+The cache is shared between the absolute-URL and page-relative-URL dispatches inside the combined HTML pass — the `raw` shapes are disjoint (absolute starts with `/`, relative doesn't), so there's no collision. The `\x00` separator between `file_dir` and `raw` prevents path-name collisions inside the cache key.
 
 ## File layout
 
@@ -264,7 +264,7 @@ Both checks set `fail: true`. Any unresolved link fails the build, blocks the Pa
 
 The plugin surfaces several conditions in its summary log lines:
 
-- **Unresolved links.** `rewrote 837 HTML and 4 CSS file(s), copied 516 asset(s) (N unresolved link(s) left as-is)`. Each match the regex picked up but couldn't resolve against `site_paths` increments the counter. The code-block skip described under [Pass 1](#pass-1-absolute-url-rewriting-html) keeps example URLs inside `<code>`/`<pre>` off this counter, so a non-zero value here is a real bug signal — usually a broken source link, or an upstream-theme change that broke a regex.
+- **Unresolved links.** `rewrote 837 HTML and 4 CSS file(s), copied 516 asset(s) (N unresolved link(s) left as-is)`. Each match the regex picked up but couldn't resolve against `site_paths` increments the counter. The [code-block skip](#code-block-skip) keeps example URLs inside `<code>`/`<pre>` off this counter, so a non-zero value here is a real bug signal — usually a broken source link, or an upstream-theme change that broke a regex.
 
 - **JS regex misses.** `could not locate navLink() in assets/js/just-the-docs.js` (or the equivalent for `initSearch()`). The corresponding patch is skipped. Means just-the-docs has shipped a new version of the function and the regex constant needs updating. The plugin emits a warning pointing at the specific constant to update.
 
@@ -280,9 +280,10 @@ The optimization story is captured in the commit history. Briefly:
 
 - **Naïve first version** (per-file `File.file?` probes for each candidate): ~30 s.
 - **+ `site_paths` Set** (O(1) lookup): down to ~10 s, before further work.
-- **+ `result_cache`, `seg_cache`, manual LCP** (replaced `Pathname.relative_path_from` per match with a string-segment comparison): down to ~3 s.
+- **+ `result_cache`, `seg_cache`, manual LCP** (replaced `Pathname.relative_path_from` per match with a string-segment comparison): down to ~7 s as the site grew past 800 pages.
+- **+ combined HTML regex** (single gsub matching both absolute and page-relative URLs in one pass — eliminating the second full file scan and the interim re-scan of code-block ranges that used to sit between two separate passes): down to ~4 s. Roughly 40% off the HTML walk.
 
-That's a ~10× total speedup compared to the naïve version. The remaining ~3 s is dominated by file I/O — reading, regex-substituting, and writing across ~1100 HTML files — plus the regex pass over the SCSS-compiled `just-the-docs-combined.css`.
+The remaining ~4 s is dominated by file I/O — reading, regex-substituting, and writing across ~830 HTML files — plus the regex pass over the SCSS-compiled `just-the-docs-combined.css`.
 
 There's an additional ~1-2 s of `FileUtils.cp` for the binary assets (images, fonts, etc.) that don't need rewriting.
 
@@ -290,7 +291,7 @@ There's an additional ~1-2 s of `FileUtils.cp` for the binary assets (images, fo
 
 - **Source-only broken links**, where the markdown points at a permalink shape that doesn't match the rendered filename, can't be fixed by the plugin — `compute_rel_url` correctly identifies the target as nonexistent and leaves the link unchanged. The strict lychee step in CI surfaces these as real errors so they get fixed at the source.
 
-- **`<a href>` values inside `<code>` blocks** *were* not distinguishable from real links at the regex level; example URLs in tutorial code samples surfaced as false-positive entries in the unresolved counter. The Pass-1/Pass-2 code-block skip (see above) now suppresses them — both the rewrite and the counter increment. Worth keeping an eye on if the upstream syntax highlighter (Rouge) ever switches away from wrapping highlighted code in `<code>` / `<pre>`.
+- **`<a href>` values inside `<code>` blocks** *were* not distinguishable from real links at the regex level; example URLs in tutorial code samples surfaced as false-positive entries in the unresolved counter. The [code-block skip](#code-block-skip) now suppresses them — both the rewrite and the counter increment. Worth keeping an eye on if the upstream syntax highlighter (Rouge) ever switches away from wrapping highlighted code in `<code>` / `<pre>`.
 
 - **The search index is hefty.** `search-data.js` is ~2.8 MB (mostly text content for every page on the site, pretty-printed). It's loaded fresh on every page navigation under `file://` since browsers don't cache aggressively across `file://` documents. The size is acceptable on SSDs but could be a couple-second delay on spinning disks. Minifying the JSON before wrapping would save ~30-40%; the plugin currently doesn't.
 
@@ -301,11 +302,11 @@ There's an additional ~1-2 s of `FileUtils.cp` for the binary assets (images, fo
 In source order in [`offlinify.rb`](offlinify.rb):
 
 - `run(site, src_dest, out_dest)` — orchestrator. Wipes contents, builds `site_paths`, normalises baseurl, walks the source tree, dispatches files by extension, kicks off the JS patch and search-data.js generation, logs the summary.
-- `rewrite!(content, regex, file_dir, file_segs, site_paths, seg_cache, result_cache, baseurl, mode:)` — Pass 1 (HTML absolute) and the CSS pass. One `gsub` per file with cache lookup per match.
-- `rewrite_rel!(content, file_dir, file_segs, site_paths, result_cache)` — Pass 2 (HTML relative). Same shape as `rewrite!` but uses `HTML_REL_HREF_RE` and `compute_rel_url`. Shares `result_cache` with Pass 1.
-- `inject_search_setup!(content, file_segs)` — Pass 3. Single regex substitution per file: finds the just-the-docs.js script tag and prepends the two new ones.
+- `rewrite_html!(content, file_dir, file_segs, site_paths, seg_cache, result_cache, baseurl, code_ranges)` — the combined HTML pass. One `gsub` per file over `HTML_COMBINED_RE`, dispatching on `raw.start_with?("/")`: absolute URLs go through `compute_relative`, page-relative URLs through `compute_rel_url`. Single cache lookup per match.
+- `rewrite_css!(content, file_dir, file_segs, site_paths, seg_cache, result_cache, baseurl)` — the CSS pass. One `gsub` per file over `CSS_URL_RE`, dispatched to `compute_relative` (CSS only carries absolute URLs in this codebase). No code-block handling — CSS has no equivalent concept.
+- `inject_search_setup!(content, file_segs)` — the second HTML pass. Single regex substitution per file: finds the just-the-docs.js script tag and prepends the two new ones.
 - `compute_relative(raw, file_segs, site_paths, seg_cache, baseurl)` — the absolute-URL resolver. Strip baseurl, probe candidates, compute LCP, return final URL.
-- `compute_rel_url(raw, file_segs, site_paths)` — the relative-URL resolver. Normalise against the current page's dir, probe candidates, return original raw plus matching suffix.
+- `compute_rel_url(raw, file_segs, site_paths)` — the page-relative-URL resolver. Normalise against the current page's dir, probe candidates, return original raw plus matching suffix.
 - `patch_jtd_js!(out_dest)` — does the `navLink()` and `initSearch()` body substitutions.
 - `build_search_data_js!(out_dest)` — generates `search-data.js` from `search-data.json`.
 
diff --git a/docs/_plugins/offlinify.rb b/docs/_plugins/offlinify.rb
index eb3a7bd..4fdf3ce 100644
--- a/docs/_plugins/offlinify.rb
+++ b/docs/_plugins/offlinify.rb
@@ -132,24 +132,29 @@
 # `_site-offline/`; Jekyll's normal `_site/` output is unaffected.
 
 module Offlinify
-  # Matches `href="..."` / `href='...'` / `src=...` attribute values
-  # whose URL starts with a single slash (not protocol-relative `//`).
-  # Captures: 1=attribute name, 2=quote char, 3=URL.
-  HTML_ATTR_RE = /\b(href|src)=(["'])(\/(?!\/)[^"']*)\2/.freeze
-
-  # Matches `href`/`src` attribute values that are page-relative --
-  # they do not start with `/`, `#`, or a URL scheme. Used to catch
-  # links that come from markdown sources verbatim (e.g.
-  # `[Foo](Foo#section)`), which Jekyll passes through unmodified
-  # and therefore do not get the baseurl prefix that `relative_url`
-  # would have added. These need their `.html` extension added so
-  # they resolve under `file://`.
+  # Matches `href="..."` / `src="..."` attribute values that need
+  # resolution against the site's file set. The URL capture (group 3)
+  # matches either form in a single pass:
   #
-  # Excluded by the lookahead:
+  #   - an absolute path (`/foo`) that does not start `//` (protocol-
+  #     relative); produced by `relative_url`. Goes through
+  #     `compute_relative` to become a page-relative URL.
+  #   - a page-relative path (`Foo`, `Foo#section`) that does not
+  #     start with `/`, `#`, or a URL scheme. These come from
+  #     markdown sources verbatim and go through `compute_rel_url`
+  #     to gain the `.html` / `/index.html` suffix needed under
+  #     `file://`.
+  #
+  # Excluded by the second alternative's lookahead:
   #   `#...`                    fragment-only (same-page anchors)
-  #   `/...` / `//...`          absolute / protocol-relative (HTML_ATTR_RE)
+  #   `/...` / `//...`          handled by the first alternative
   #   `mailto:`, `http:`, etc.  any RFC 3986 URL scheme
-  HTML_REL_HREF_RE = %r{\b(href|src)=(["'])((?![#/]|[a-zA-Z][a-zA-Z0-9+.\-]*:)[^"']+)\2}.freeze
+  #
+  # Captures: 1=attribute name, 2=quote char, 3=URL. A single
+  # combined regex halves the per-file regex work over an older
+  # split between two separate regexes -- two full gsubs plus an
+  # interim re-scan for code-block ranges between them.
+  HTML_COMBINED_RE = %r{\b(href|src)=(["'])(\/(?!\/)[^"']*|(?![#/]|[a-zA-Z][a-zA-Z0-9+.\-]*:)[^"']+)\2}.freeze
 
   # Matches `url(...)` in CSS where the URL starts with a single slash.
   # The URL may be bare or wrapped in single/double quotes. Captures:
@@ -317,10 +322,6 @@ def self.offline_excluded?(rel, patterns)
   # inside.
   CODE_BLOCK_RE = /<(code|pre)\b[^>]*>(.*?)<\/\1>/m.freeze
 
-  # Sentinel for callers (CSS rewrite) that don't have code-block
-  # context. Avoids allocating a throwaway array per file.
-  EMPTY_RANGES = [].freeze
-
   # Returns an array of `[body_start, body_end]` byte ranges for every
   # code-block body in `content`. Empty when there are no code blocks.
   # Used in conjunction with `in_code_block?` to gate the rewrite
@@ -440,18 +441,11 @@ def self.run(site, src_dest, out_dest)
         content = File.binread(src_path)
         file_dir  = File.dirname(out_path)
         file_segs = file_dir_segs_from_rel(rel)
-        # Compute code-block byte ranges before each rewrite pass.
-        # Pass 1 may shift downstream offsets (it rewrites href/src
-        # attribute values, which usually grow), so Pass 2 needs a
-        # fresh scan against the post-Pass-1 content.
         code_ranges = code_block_ranges(content)
-        changed_url, misses = rewrite!(content, HTML_ATTR_RE, file_dir, file_segs, site_paths, seg_cache, result_cache, baseurl, code_ranges, mode: :html)
+        changed_url, misses = rewrite_html!(content, file_dir, file_segs, site_paths, seg_cache, result_cache, baseurl, code_ranges)
         unresolved += misses
-        code_ranges = code_block_ranges(content) if changed_url
-        changed_rel, rel_misses = rewrite_rel!(content, file_dir, file_segs, site_paths, result_cache, code_ranges)
-        unresolved += rel_misses
         changed_search = inject_search_setup!(content, file_segs)
-        if changed_url || changed_rel || changed_search
+        if changed_url || changed_search
           FileUtils.mkdir_p(File.dirname(out_path))
           File.binwrite(out_path, content)
           rewritten_html += 1
@@ -463,7 +457,7 @@ def self.run(site, src_dest, out_dest)
         content = File.binread(src_path)
         file_dir  = File.dirname(out_path)
         file_segs = file_dir_segs_from_rel(rel)
-        changed, misses = rewrite!(content, CSS_URL_RE, file_dir, file_segs, site_paths, seg_cache, result_cache, baseurl, EMPTY_RANGES, mode: :css)
+        changed, misses = rewrite_css!(content, file_dir, file_segs, site_paths, seg_cache, result_cache, baseurl)
         unresolved += misses
         if changed
           FileUtils.mkdir_p(File.dirname(out_path))
@@ -595,40 +589,60 @@ def self.build_search_data_js!(out_dest)
     js.bytesize
   end
 
-  # Mutates `content` in place via gsub. Returns
-  # `[changed_bool, unresolved_count]`. Per-match work is a single
-  # Hash lookup in `result_cache` -- the heavy lifting (URL
-  # resolution, LCP walk, segment encoding) runs only on cache miss.
+  # Mutates `content` in place via a single gsub matching both
+  # absolute (`/...`) and page-relative (`Foo`, `Foo#frag`) href/src
+  # URLs. Returns `[changed_bool, unresolved_count]`. Per-match work
+  # is a single Hash lookup in `result_cache` -- the heavy lifting
+  # (URL resolution, LCP walk, segment encoding) runs only on cache
+  # miss.
+  #
+  # Dispatches inside the gsub block on whether `raw` starts with
+  # `/`: absolute URLs go through `compute_relative` (resolves to a
+  # page-relative form), page-relative ones go through
+  # `compute_rel_url` (probes the filesystem for `<rel>`,
+  # `<rel>.html`, `<rel>/index.html` and re-attaches the matching
+  # suffix). Both share `result_cache` since their cache keys are
+  # disjoint -- absolute starts with `/`, relative doesn't.
+  #
+  # `compute_rel_url` may return the input unchanged when the file
+  # already exists at the relative path verbatim (e.g. `Foo.html`
+  # from a sibling markdown source); this is treated as "no rewrite
+  # needed, not a miss".
   #
   # `code_ranges` is an array of `[start, end]` byte ranges covering
-  # the bodies of `<code>` / `<pre>` blocks in `content`; matches
-  # whose offset falls in any range are left untouched and do not
-  # count as unresolved. Pass an empty array (or omit `code_ranges`
-  # for the CSS mode, which has no such concept).
-  def self.rewrite!(content, regex, file_dir, file_segs, site_paths, seg_cache, result_cache, baseurl, code_ranges, mode:)
+  # the bodies of `<code>` / `<pre>` blocks; matches whose offset
+  # falls inside any range are left untouched and do not count as
+  # unresolved.
+  def self.rewrite_html!(content, file_dir, file_segs, site_paths, seg_cache, result_cache, baseurl, code_ranges)
     misses = 0
     changed = false
 
-    new_content = content.gsub(regex) do
+    new_content = content.gsub(HTML_COMBINED_RE) do
       match = Regexp.last_match
       next match[0] if !code_ranges.empty? && in_code_block?(match.begin(0), code_ranges)
 
-      raw = mode == :html ? match[3] : match[2]
+      raw = match[3]
       cache_key = "#{file_dir}\x00#{raw}"
       rel = result_cache.fetch(cache_key) do
-        result_cache[cache_key] = compute_relative(raw, file_segs, site_paths, seg_cache, baseurl)
+        result_cache[cache_key] =
+          if raw.start_with?("/")
+            compute_relative(raw, file_segs, site_paths, seg_cache, baseurl)
+          else
+            compute_rel_url(raw, file_segs, site_paths)
+          end
       end
+
       if rel.nil?
         misses += 1
         match[0]
+      elsif rel == raw
+        # File exists at the relative path verbatim; the link is
+        # already correct (relative branch only -- compute_relative
+        # never returns the input unchanged).
+        match[0]
       else
         changed = true
-        if mode == :html
-          %(#{match[1]}=#{match[2]}#{rel}#{match[2]})
-        else
-          quote = match[1]
-          "url(#{quote}#{rel}#{quote})"
-        end
+        %(#{match[1]}=#{match[2]}#{rel}#{match[2]})
       end
     end
 
@@ -636,38 +650,30 @@ def self.rewrite!(content, regex, file_dir, file_segs, site_paths, seg_cache, re
     [changed, misses]
   end
 
-  # Companion to `rewrite!` for page-relative URLs that didn't go
-  # through `relative_url` (e.g. links that came straight from
-  # markdown sources like `[Foo](Foo#section)`). Mutates `content`
-  # in place. Returns `[changed_bool, unresolved_count]`. Shares the
-  # `result_cache` with the absolute-URL pass since the keyed `raw`
-  # values are disjoint (absolute URLs start with `/`, relative ones
-  # don't). `code_ranges` excludes matches inside `<code>` / `<pre>`
-  # blocks (same handling as `rewrite!`).
-  def self.rewrite_rel!(content, file_dir, file_segs, site_paths, result_cache, code_ranges)
+  # Mutates `content` in place via gsub over `url(...)` references
+  # that start with `/`. Returns `[changed_bool, unresolved_count]`.
+  # Per-match work is a single Hash lookup in `result_cache` -- the
+  # heavy lifting (URL resolution, LCP walk, segment encoding) runs
+  # only on cache miss. CSS has no code-block concept, so there is
+  # no need to gate matches by offset the way `rewrite_html!` does.
+  def self.rewrite_css!(content, file_dir, file_segs, site_paths, seg_cache, result_cache, baseurl)
     misses = 0
     changed = false
 
-    new_content = content.gsub(HTML_REL_HREF_RE) do
+    new_content = content.gsub(CSS_URL_RE) do
       match = Regexp.last_match
-      next match[0] if !code_ranges.empty? && in_code_block?(match.begin(0), code_ranges)
-
-      raw = match[3]
+      raw = match[2]
+      quote = match[1]
       cache_key = "#{file_dir}\x00#{raw}"
       rel = result_cache.fetch(cache_key) do
-        result_cache[cache_key] = compute_rel_url(raw, file_segs, site_paths)
+        result_cache[cache_key] = compute_relative(raw, file_segs, site_paths, seg_cache, baseurl)
       end
       if rel.nil?
         misses += 1
         match[0]
-      elsif rel == raw
-        # File already exists at the relative path verbatim; the
-        # link is correct as-is (e.g. `Foo.html` from a sibling
-        # markdown source).
-        match[0]
       else
         changed = true
-        %(#{match[1]}=#{match[2]}#{rel}#{match[2]})
+        "url(#{quote}#{rel}#{quote})"
       end
     end
 

From 6e9d62ffbfee9451b8abc0c4de6ed4ebf22eb65a Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 17 May 2026 17:27:34 +0200
Subject: [PATCH 3/6] Integrate offlinification into the file processing flow.

---
 docs/_plugins/offlinify.md | 110 ++++++++---
 docs/_plugins/offlinify.rb | 392 +++++++++++++++++++++++++------------
 2 files changed, 345 insertions(+), 157 deletions(-)

diff --git a/docs/_plugins/offlinify.md b/docs/_plugins/offlinify.md
index 1d1aac4..f9176a4 100644
--- a/docs/_plugins/offlinify.md
+++ b/docs/_plugins/offlinify.md
@@ -1,6 +1,6 @@
 # Offlinify
 
-`_plugins/offlinify.rb` produces a `file://`-browsable copy of the rendered site. Every page-to-page link is rewritten to a page-relative path with an explicit file extension; the two just-the-docs JS functions that break under `file://` are patched; the lunr search index is rewired to load from a `<script src=>` instead of an XHR call. The result is a fully self-contained tree that opens cleanly when you double-click `index.html` on disk — no HTTP server required.
+`_plugins/offlinify.rb` produces a `file://`-browsable copy of the rendered site. The plugin hooks into Jekyll's render pipeline per page: it captures each rendered `page.output` in memory, rewrites every page-to-page link to a page-relative path with an explicit file extension, and writes the result straight to `_site-offline/<rel>` — no detour through disk. After Jekyll's WRITE phase, a final hook copies static files (images, fonts, the just-the-docs.js theme asset), patches the two just-the-docs JS functions that break under `file://`, and rewires the lunr search index to load from a `<script src=>` instead of an XHR call. The result is a fully self-contained tree that opens cleanly when you double-click `index.html` on disk — no HTTP server required.
 
 This file sits in `_plugins/` for two reasons: it lives next to the code it documents, and Jekyll's `_plugins/` folder is plugin-only territory, so this Markdown never gets rendered into the public site.
 
@@ -18,38 +18,84 @@ Pure Jekyll can't fix any of these. `relative_url` is site-relative, not page-re
 
 ## When it runs
 
-Activated by `also_build_offline: true` (the default in `_config.yml`). Reads from `site.dest` (i.e. `_site/`) and writes to `<site.dest>-offline/`. The hook at the bottom of `offlinify.rb`:
+Activated by `also_build_offline: true` (the default in `_config.yml`). The plugin registers four hooks that fire across the build:
 
 ```ruby
+Jekyll::Hooks.register :site, :pre_render do |site|
+  next unless site.config["also_build_offline"]
+  Offlinify.setup(site)
+end
+
+Jekyll::Hooks.register :pages, :post_render do |page|
+  Offlinify.process_page(page)
+end
+
+Jekyll::Hooks.register :documents, :post_render do |doc|
+  Offlinify.process_page(doc)
+end
+
 Jekyll::Hooks.register :site, :post_write do |site|
   next unless site.config["also_build_offline"]
-  Offlinify.run(site, site.dest, "#{site.dest}-offline")
+  Offlinify.finish(site)
 end
 ```
 
+`Offlinify.setup` reads from `site.config` and the in-memory `site.pages + site.static_files + site.documents`, wipes `<site.dest>-offline/`, and seeds per-build state on the module's `@state` ivar. The per-page hooks transform `page.output` and write straight to `_site-offline/`. `Offlinify.finish` reads static files from `site.dest` (`_site/`, now fully written by Jekyll's WRITE phase) and copies them across, then patches `just-the-docs.js` and writes `search-data.js`.
+
 One Jekyll invocation produces `_site/`, `_site-offline/` (this plugin), and `_site-pdf/` (via `pdfify.rb`). Flip the flag to `false` if you only want the online site.
 
+**Incremental mode (`--incremental`) is not supported.** The per-page write model writes only the changed pages while the pre_render hook still wipes the offline tree — net result: an incomplete offline build. `setup` detects the flag and emits a warning instead of running. Use plain `jekyll build` for the offline tree.
+
 ## The build flow
 
-After Jekyll's WRITE phase completes, the hook fires `Offlinify.run(site, src_dest, out_dest)`, which does the following:
+Three phases, four hook callbacks.
+
+### Phase 1: setup
+
+Fires at `:site, :pre_render` — once at the start of the build, after Jekyll has read the source tree and generated all pages (including jekyll-redirect-from stubs and SCSS-derived CSS pages) but before any page renders.
+
+1. **Bail on `--incremental`.** Set `@state = nil` and emit a warning. The per-page write model would leave the offline tree incomplete — the wipe runs unconditionally, but only changed pages re-fire their post_render hook.
+
+2. **Wipe the output directory's *contents***. The directory itself is preserved across builds — recreating it makes Jekyll's watcher report a bare `_site-offline` change event (no trailing slash, since the directory is momentarily absent at notification time) that the YAML exclude entry `_site-offline` doesn't match (jekyll-watch auto-appends a trailing slash to directory excludes, turning the rule into the regex `_site-offline/`), and the result is an infinite rebuild loop on `jekyll serve`.
 
-1. **Wipe the output directory's *contents***. The directory itself is preserved across builds — recreating it makes Jekyll's watcher report a bare `_site-offline` change event (no trailing slash, since the directory is momentarily absent at notification time) that the YAML exclude entry `_site-offline` doesn't match (jekyll-watch auto-appends a trailing slash to directory excludes, turning the rule into the regex `_site-offline/`), and the result is an infinite rebuild loop on `jekyll serve`.
+3. **Build `site_paths`** from Jekyll's in-memory model (`site.pages + site.static_files + site.documents`). Each item's `destination(site.dest)` gives the absolute file path Jekyll will write; converting to a site-rooted forward-slash form yields keys like `/tB/Core/Const.html`. The keys are *decoded* — filesystem names like `Form Designer.html` go in literally, not `Form%20Designer.html`. Resolution in `compute_relative` is then an O(1) `Set#include?` probe per candidate, instead of 2-3 `File.file?` syscalls each (very slow on Windows).
 
-2. **Build `site_paths`.** Walk `src_dest` once and bucket every file under its site-rooted forward-slash path (`/tB/Core/Const.html`, `/assets/js/just-the-docs.js`, etc.). The keys are *decoded* — filesystem names like `Form Designer.html` go in literally, not `Form%20Designer.html`. Resolution in `compute_relative` is then an O(1) `Set#include?` probe per candidate, instead of 2-3 `File.file?` syscalls each (very slow on Windows). Without this, the offlinify pass takes ~30 s on this site; with it, the pass is ~3 s.
+4. **Normalise `baseurl`.** Read `site.config["baseurl"]`, strip trailing slashes, prepend a leading slash if missing. The result matches the prefix `relative_url` actually emits in the rendered HTML — e.g. `/twinBASIC-docs` on a GitHub Pages project site. Used during URL resolution to strip the prefix before probing `site_paths`.
 
-3. **Normalise `baseurl`.** Read `site.config["baseurl"]`, strip trailing slashes, prepend a leading slash if missing. The result matches the prefix `relative_url` actually emits in the rendered HTML — e.g. `/twinBASIC-docs` on a GitHub Pages project site. Used during URL resolution to strip the prefix before probing `site_paths`.
+5. **Seed state** on the module's `@state` ivar so the per-page and finish hooks can pick up where setup left off: caches (`seg_cache`, `result_cache`), counters, normalised baseurl, exclude patterns, dest paths, cumulative timer. Cleared at the end of `finish` so a fresh build starts clean.
 
-4. **Walk the source tree.** For each file:
-   - If the file matches a pattern in `site.config["offline_exclude"]` (see [Exclude list](#exclude-list)): skip the copy so the online `_site/` keeps it and the offline tree doesn't.
-   - `.html`: read once, run two transformation passes in order (combined HTML URL rewrite, search-setup injection), write back if any pass changed content.
-   - `.css`: read, run the `url()` rewrite, write back.
-   - Anything else (images, fonts, JSON, JS): plain `FileUtils.cp` into the offline tree.
+### Phase 2: process_page
 
-5. **Patch `assets/js/just-the-docs.js`.** Replace the `navLink()` and `initSearch()` function bodies with offline-friendly versions.
+Fires at `:pages, :post_render` and `:documents, :post_render` — once per page after Jekyll renders it. `page.output` is the final HTML/CSS/etc bytes; the plugin transforms it and writes the result to `_site-offline/<rel>`. Jekyll's WRITE phase writes the same `page.output` to `_site/<rel>` a moment later, so the online and offline files come from the same in-memory string — no re-read.
 
-6. **Generate `assets/js/search-data.js`.** Read the rendered `search-data.json` (it's only present when `search_enabled` is true, which is the default in `_config.yml`), wrap in `window.SEARCH_DATA = {...};`, write next to the JSON.
+For each page:
 
-7. **Log the summary.** Three or four lines under the `Offlinify:` topic prefix, ending with `Offlinifier ran in Xms.` — same shape as the `build-phase-timing.rb` plugin's lines, so the cost shows up next to Jekyll's own phase timings.
+1. **Compute `rel`** from `page.destination(@state[:dest])` via a plain string slice (`dest_path[(@state[:dest_root_fs].length + 1)..]`) rather than a Pathname round-trip. `Pathname#relative_path_from` is roughly 2 ms per call on Windows and would dominate per-page cost on a 1000+ page build.
+
+2. **Check `offline_exclude`** (see [Exclude list](#exclude-list)). Matched files increment the `excluded_files` counter and skip the write.
+
+3. **Detect jekyll-redirect-from stubs** by class-name string check (`page.class.name == "JekyllRedirectFrom::RedirectPage"`). The redirect stubs aren't useful in the offline tree — their meta-refresh, canonical link, and fallback `<a>` all point at the live online URL (`https://docs.twinbasic.com/...` when `site.url` is set), so following one offline requires network access and lands on the live site rather than the local file. Skip the write; count them under `excluded_files`. The class-name string check is used rather than `is_a?` so the plugin still loads if jekyll-redirect-from is removed.
+
+4. **Dispatch on output extension:**
+   - `.html`: dup `page.output`, scan for code-block ranges, run the combined HTML URL rewrite (see [HTML URL rewriting](#html-url-rewriting)), inject the search-setup script tags, write.
+   - `.css`: dup `page.output`, run the `url()` rewrite (see [CSS `url()` rewriting](#css-url-rewriting)), write.
+   - Anything else (XML feeds, JSON, etc.): write `page.output` verbatim.
+
+5. **Accumulate self-time** into `@state[:cumulative_ms]`. The reported total at the end is just Offlinify's CPU time across all hook invocations, not the wall-clock between pre_render and post_write (which would include Jekyll's render and write phases between our hooks).
+
+### Phase 3: finish
+
+Fires at `:site, :post_write` — once after Jekyll's WRITE phase has populated `_site/`.
+
+1. **Copy static files** (`site.static_files`) from `_site/` to `_site-offline/`. Static files don't fire `:pages, :post_render`, so they're handled here. The `offline_exclude` check runs again for each.
+
+2. **Patch `assets/js/just-the-docs.js`** in `_site-offline/`. Replace the `navLink()` and `initSearch()` function bodies with offline-friendly versions.
+
+3. **Generate `assets/js/search-data.js`.** Read the `search-data.json` that Phase 2 wrote (the jekyll-search Page object renders the JSON, which `process_page` captures and writes verbatim), wrap in `window.SEARCH_DATA = {...};`, write next to the JSON.
+
+4. **Log the summary.** Three or four lines under the `Offlinify:` topic prefix, ending with `Offlinifier ran in Xms.` (cumulative self-time, not wall-clock).
+
+5. **Clear `@state`** so a subsequent build starts with no leftover counters or caches.
 
 ## Transformation passes
 
@@ -212,20 +258,22 @@ offline_exclude:
 
 Patterns are `File.fnmatch`-style with `File::FNM_PATHNAME`, matched against each file's site-rooted forward-slash path. `*` does **not** cross directory separators, so `*.bat` catches only top-level `.bat` files; use `**/*.bat` to match at any depth. Specific paths like `subdir/foo.txt` also work and match exactly.
 
-A missing or empty `offline_exclude` entry skips the step entirely — the offline tree gets every file Jekyll produced.
+A missing or empty `offline_exclude` entry skips the pattern check entirely.
 
 The exclude check runs in two places:
 
-1. **Before** the `site_paths` Set is built, so URL-resolution candidates can't point at an excluded target (a stray `<a href="/sitemap.xml">` in the source would simply fail to resolve, instead of resolving to a now-missing file).
-2. **Inside** the main file walk, where the copy is skipped so the file never appears in `_site-offline/`.
+1. **Inside `build_site_paths` in `setup`**, so URL-resolution candidates can't point at an excluded target (a stray `<a href="/sitemap.xml">` in the source would simply fail to resolve, instead of resolving to a now-missing file).
+2. **Inside `process_page` and the static-file loop in `finish`**, where the write is skipped so the file never appears in `_site-offline/`.
+
+In addition to the pattern-based excludes, **jekyll-redirect-from stubs are unconditionally dropped** from the offline tree (detected by the `JekyllRedirectFrom::RedirectPage` class-name check in `process_page`). The stubs contain only a meta-refresh / canonical link / fallback `<a>`, all pointing at the live online URL — following one offline requires network access and lands on the live site, defeating the offline scenario. Source markdown should use the canonical URL directly rather than relying on the redirect; the strict lychee step in CI surfaces any source link that still goes through a redirect.
 
-The summary log line reports the count: `… excluded 7 file(s) …`.
+The summary log line reports the count: `… excluded 294 file(s) …` (pattern-matched + redirect stubs combined).
 
 ## Caches
 
 Three caches keep the per-match work to a single Hash lookup once warmed up:
 
-1. **`site_paths`** (`Set` of strings). Built once at the start of `run`. Every file path under `src_dest`, keyed by its site-rooted forward-slash form (`/tB/Core/Const.html`). Used by `compute_relative` and `compute_rel_url` to probe candidate paths.
+1. **`site_paths`** (`Set` of strings). Built once in `setup` from `site.pages + site.static_files + site.documents`. Every file path that Jekyll will write, keyed by its site-rooted forward-slash form (`/tB/Core/Const.html`). Used by `compute_relative` and `compute_rel_url` to probe candidate paths.
 
 2. **`seg_cache`** (`Hash` of `site_path` → `[decoded_segs, encoded_segs]`). Lazily populated. For each unique target site path that the URL rewriter resolves to, this holds the decoded path segments (used for LCP comparison against filesystem-derived `file_segs`) and the URL-encoded segments (joined for the output URL). Most segments are URL-safe and share strings between the two arrays.
 
@@ -239,7 +287,7 @@ The offline build touches the following files:
 
 | Path | Role |
 |------|------|
-| `docs/_plugins/offlinify.rb` | The plugin. Hooks `:site, :post_write`, runs all the passes. |
+| `docs/_plugins/offlinify.rb` | The plugin. Hooks `:site, :pre_render` (setup), `:pages, :post_render` + `:documents, :post_render` (per-page write), `:site, :post_write` (static files, JS patches, search-data.js). |
 | `docs/_plugins/offlinify.md` | This file. |
 | `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. |
@@ -250,7 +298,7 @@ The offline build touches the following files:
 
 ## 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 — the baseurl normalisation at the start of `run` produces the right prefix to strip.
+`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:
 
@@ -270,7 +318,7 @@ The plugin surfaces several conditions in its summary log lines:
 
 - **Missing `search-data.json`.** Silent — the search-data.js generation step is a no-op. The per-page script tag injection still runs, so each page will request `search-data.js` and the browser will log a 404. The patched `initSearch()` will hit its `window.SEARCH_DATA not found` branch and log a console message.
 
-- **Real broken links in markdown sources.** Caught by the strict lychee step in CI (or by `check.bat` locally). These don't surface in the offlinify summary because the rewrite passes correctly identify them as unresolvable and leave them alone — that's the right behavior, the source markdown needs fixing.
+- **Real broken links in markdown sources.** Caught by the strict lychee step in CI (or by `check.bat` locally). These don't surface in the offlinify summary because the rewrite passes correctly identify them as unresolvable and leave them alone — that's the right behavior, the source markdown needs fixing. Since jekyll-redirect-from stubs are dropped from the offline tree, any source markdown linking at a `redirect_from` URL surfaces as a broken offline link until the source link is updated to point at the canonical URL.
 
 - **`_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).
 
@@ -282,10 +330,11 @@ The optimization story is captured in the commit history. Briefly:
 - **+ `site_paths` Set** (O(1) lookup): down to ~10 s, before further work.
 - **+ `result_cache`, `seg_cache`, manual LCP** (replaced `Pathname.relative_path_from` per match with a string-segment comparison): down to ~7 s as the site grew past 800 pages.
 - **+ combined HTML regex** (single gsub matching both absolute and page-relative URLs in one pass — eliminating the second full file scan and the interim re-scan of code-block ranges that used to sit between two separate passes): down to ~4 s. Roughly 40% off the HTML walk.
+- **+ per-page hook architecture** (`:pages, :post_render` consumes `page.output` in memory rather than re-reading the rendered HTML from `_site/` at `:site, :post_write`): the per-file `File.binread` is eliminated. Cumulative self-time across hooks is ~5-6 s on the current ~830-page site, dominated by per-page Jekyll hook dispatch overhead and the per-page `File.binwrite`. Skipping the ~290 jekyll-redirect-from stubs (see [Phase 2](#phase-2-process_page)) trims ~400 ms.
 
-The remaining ~4 s is dominated by file I/O — reading, regex-substituting, and writing across ~830 HTML files — plus the regex pass over the SCSS-compiled `just-the-docs-combined.css`.
+The remaining cumulative time is mostly `File.binwrite` across ~830 HTML files (Windows file I/O on NTFS is the dominant cost) plus the regex pass over the SCSS-compiled `just-the-docs-combined.css`.
 
-There's an additional ~1-2 s of `FileUtils.cp` for the binary assets (images, fonts, etc.) that don't need rewriting.
+The static-file copy in `finish` adds an additional ~200 ms of `FileUtils.cp` for the binary assets (images, fonts, etc.) that don't need rewriting.
 
 ## Known limitations
 
@@ -301,13 +350,18 @@ There's an additional ~1-2 s of `FileUtils.cp` for the binary assets (images, fo
 
 In source order in [`offlinify.rb`](offlinify.rb):
 
-- `run(site, src_dest, out_dest)` — orchestrator. Wipes contents, builds `site_paths`, normalises baseurl, walks the source tree, dispatches files by extension, kicks off the JS patch and search-data.js generation, logs the summary.
+- `setup(site)` — `:site, :pre_render` hook entry. Builds `site_paths` from the in-memory page set, wipes the offline tree, seeds per-build state on `@state`. Bails out with a warning if `--incremental` is set.
+- `normalize_baseurl(raw_baseurl)` — helper for `setup`. Coerces the configured baseurl to either empty string or `/segment...` with no trailing slash, matching the form `relative_url` actually prepends.
+- `build_site_paths(site, exclude_patterns)` — helper for `setup`. Iterates `site.pages + site.static_files + site.documents` and builds the URL Set from each item's `destination(site.dest)`, decoded and forward-slash-normalised.
+- `wipe_out_dest_contents(out_dest)` — helper for `setup`. Removes the offline tree contents while leaving the directory itself in place (see [Phase 1](#phase-1-setup)).
+- `process_page(page)` — `:pages, :post_render` and `:documents, :post_render` hook entry. Transforms `page.output` and writes the offline copy. Dispatches on output extension and on page class (skips jekyll-redirect-from stubs entirely).
+- `finish(site)` — `:site, :post_write` hook entry. Copies static files from `_site/` to `_site-offline/`, patches just-the-docs.js, generates search-data.js, logs the summary, clears `@state`.
 - `rewrite_html!(content, file_dir, file_segs, site_paths, seg_cache, result_cache, baseurl, code_ranges)` — the combined HTML pass. One `gsub` per file over `HTML_COMBINED_RE`, dispatching on `raw.start_with?("/")`: absolute URLs go through `compute_relative`, page-relative URLs through `compute_rel_url`. Single cache lookup per match.
 - `rewrite_css!(content, file_dir, file_segs, site_paths, seg_cache, result_cache, baseurl)` — the CSS pass. One `gsub` per file over `CSS_URL_RE`, dispatched to `compute_relative` (CSS only carries absolute URLs in this codebase). No code-block handling — CSS has no equivalent concept.
-- `inject_search_setup!(content, file_segs)` — the second HTML pass. Single regex substitution per file: finds the just-the-docs.js script tag and prepends the two new ones.
+- `inject_search_setup!(content, file_segs)` — the second HTML transformation. Single regex substitution per file: finds the just-the-docs.js script tag and prepends the two new ones.
 - `compute_relative(raw, file_segs, site_paths, seg_cache, baseurl)` — the absolute-URL resolver. Strip baseurl, probe candidates, compute LCP, return final URL.
 - `compute_rel_url(raw, file_segs, site_paths)` — the page-relative-URL resolver. Normalise against the current page's dir, probe candidates, return original raw plus matching suffix.
 - `patch_jtd_js!(out_dest)` — does the `navLink()` and `initSearch()` body substitutions.
 - `build_search_data_js!(out_dest)` — generates `search-data.js` from `search-data.json`.
 
-Together these are ~250 lines of Ruby plus inline JS replacement strings. The rest of the file is doc comments.
+Together these are ~280 lines of Ruby plus inline JS replacement strings. The rest of the file is doc comments.
diff --git a/docs/_plugins/offlinify.rb b/docs/_plugins/offlinify.rb
index 4fdf3ce..72132e0 100644
--- a/docs/_plugins/offlinify.rb
+++ b/docs/_plugins/offlinify.rb
@@ -5,13 +5,14 @@
 require "set"
 
 # Produces a `file://`-browsable copy of the rendered site. Activated
-# by `also_build_offline: true` in `_config.yml` (the default). Plain
-# `bundle exec jekyll build` writes the online site to `site.dest`
-# (`_site/`) as usual, then this plugin copies the tree to
-# `<site.dest>-offline` (`_site-offline/`), rewrites every URL to a
-# page-relative form, patches a couple of just-the-docs JS issues, and
-# wires up the search index to load from a `<script src=>` instead of
-# XHR. One Jekyll invocation produces both `_site/` and `_site-offline/`
+# by `also_build_offline: true` in `_config.yml` (the default). For
+# each page Jekyll renders, this plugin captures the in-memory output
+# and writes a URL-rewritten copy straight to `<site.dest>-offline`
+# (`_site-offline/`) -- no detour through disk. After Jekyll's WRITE
+# phase completes, static files (images, fonts, the just-the-docs.js
+# theme asset, etc.) get copied across, the just-the-docs.js navigation
+# and search bodies get patched, and `search-data.js` is generated.
+# One Jekyll invocation produces both `_site/` and `_site-offline/`
 # (and, via `_plugins/pdfify.rb`, `_site-pdf/`).
 #
 # === Why post-process at all? ===
@@ -36,6 +37,46 @@
 # rendering links -- and per-page `permalink:` frontmatter overrides
 # any global URL-shape change. The fix has to come after render.
 #
+# === Build flow ===
+#
+# Three Jekyll hooks orchestrate the build:
+#
+#   1. `:site, :pre_render` -- builds `site_paths` from
+#      `site.pages + site.static_files + site.documents`, wipes the
+#      contents of `_site-offline/`, and initialises per-build state
+#      (caches, counters, normalised baseurl) on the module's `@state`
+#      ivar so the later hooks can read it.
+#
+#   2. `:pages, :post_render` and `:documents, :post_render` -- fire
+#      once per page after Jekyll renders it. `page.output` is the
+#      final HTML/CSS/etc bytes; the plugin transforms it and writes
+#      the result to `_site-offline/<rel>`. Jekyll's WRITE phase
+#      writes the same `page.output` to `_site/<rel>` a moment later,
+#      so the online and offline files come from the same in-memory
+#      string -- no re-read.
+#
+#   3. `:site, :post_write` -- once Jekyll has finished writing
+#      `_site/`, this hook copies static files (images, fonts, raw
+#      JS/JSON the theme ships verbatim, the just-the-docs.js asset)
+#      from `_site/` into `_site-offline/`, patches
+#      `_site-offline/assets/js/just-the-docs.js`, and generates
+#      `_site-offline/assets/js/search-data.js` from the
+#      `search-data.json` produced in phase 2.
+#
+# Two payoffs over the older single-pass walk of `_site/` at
+# `:site, :post_write`:
+#
+#   * Full builds skip the per-page HTML re-read (one File.binread
+#     per rendered page, eliminated).
+#   * `jekyll serve` rebuilds inherit the same speedup -- the
+#     post-write file walk is gone.
+#
+# Incremental mode (`--incremental`) is not supported: pre_render
+# fires and wipes `_site-offline/`, but only changed pages re-fire
+# their post_render hook, so unchanged pages would disappear from
+# the offline tree. The setup hook detects the flag and skips the
+# offline build with a warning.
+#
 # === URL rewriting ===
 #
 # For each HTML file: regex-substitute every `href="..."` / `src="..."`
@@ -124,9 +165,13 @@
 #
 # === Compatibility ===
 #
-# Reads `site.dest` and `site.config['also_build_offline']`. Writes a
-# fresh `<site.dest>-offline/` tree (wiping any prior contents).
-# Touches no files outside that.
+# Reads `site.dest`, `site.config['also_build_offline']`,
+# `site.config['baseurl']`, `site.config['offline_exclude']`, and
+# `site.config['incremental']` (the last to bail out with a warning).
+# Reads each rendered page's `page.output` in memory; reads static
+# files from `site.dest` after WRITE. Writes a fresh
+# `<site.dest>-offline/` tree (wiping any prior contents at the start
+# of the build). Touches no files outside that.
 #
 # If the plugin is removed: the build silently stops producing
 # `_site-offline/`; Jekyll's normal `_site/` output is unaffected.
@@ -343,42 +388,111 @@ def self.in_code_block?(offset, ranges)
     ranges.any? { |s, e| offset >= s && offset < e }
   end
 
-  def self.run(site, src_dest, out_dest)
-    return unless Dir.exist?(src_dest)
-
-    start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-
-    # Jekyll's `relative_url` filter prepends `site.baseurl` to every
-    # URL it produces, so when baseurl is non-empty (e.g. on a Pages
-    # project site without a custom domain, where configure-pages
-    # outputs a `/repo-name` base_path), the rendered HTML hrefs look
-    # like `/<baseurl>/foo` while files in site_paths are stored
-    # without the prefix. Strip the prefix during resolution so the
-    # offline rewrite works regardless of baseurl. Normalised to
-    # either empty string or `/segment...` with no trailing slash.
-    # Normalise to either empty or `/segment...` with no trailing
-    # slash, matching the form `relative_url` prepends to URLs in the
-    # rendered HTML. The configured value may lack a leading slash
-    # (Jekyll adds one when emitting), and may carry a trailing slash
-    # the rendered URLs don't have.
-    baseurl = (site.config["baseurl"] || "").to_s.sub(%r{/+\z}, "")
-    baseurl = "/#{baseurl}" if !baseurl.empty? && !baseurl.start_with?("/")
+  # Per-build state, populated in `setup` and cleared in `finish`.
+  # The :pages, :post_render and :site, :post_write hooks read it
+  # via `@state`. Nil between builds, and nil during a build that
+  # opted out (e.g. when `--incremental` is set).
+  @state = nil
+
+  # `:site, :pre_render` hook entry. Builds the URL-resolution set,
+  # wipes the offline tree, and seeds the per-build state. Bails out
+  # cleanly when incremental mode is on -- the per-page write model
+  # would leave stale files for pages Jekyll chose not to re-render.
+  def self.setup(site)
+    if site.config["incremental"]
+      @state = nil
+      Jekyll.logger.warn "Offlinify:",
+        "incremental mode is not supported; _site-offline/ will not be " \
+        "updated this build. Disable also_build_offline or rebuild " \
+        "without --incremental."
+      return
+    end
 
-    # Patterns for files Jekyll wrote into _site/ that have no purpose
-    # in the offline tree (Pages CNAME, sitemap, robots, etc.). Loaded
-    # from `site.config['offline_exclude']` so the policy lives in
-    # _config.yml; an empty / missing entry skips this step entirely.
+    start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    out_dest = "#{site.dest}-offline"
     exclude_patterns = Array(site.config["offline_exclude"]).map(&:to_s)
 
-    # Wipe the offline output tree but keep the `_site-offline/`
-    # directory itself in place. (Deleting and recreating the
-    # directory surfaces in jekyll-watch as a bare `_site-offline`
-    # change event -- no trailing slash, since the directory was
-    # momentarily absent at notification time -- which the exclude
-    # entry's auto-generated `_site\-offline\/` regex does not match.
-    # The result was an infinite rebuild loop on `jekyll serve`.
-    # Cleaning contents in place keeps every event under
-    # `_site-offline/...`, where the exclude does match.)
+    @state = {
+      dest: site.dest,
+      # Pre-normalised forward-slash form of site.dest. Used to
+      # compute `rel` from `page.destination(dest)` via a plain
+      # string slice in process_page -- much faster than wrapping
+      # both in Pathname and calling relative_path_from per page
+      # (Pathname is notably slow on Windows).
+      dest_root_fs: site.dest.tr("\\", "/"),
+      out_dest: out_dest,
+      baseurl: normalize_baseurl(site.config["baseurl"]),
+      exclude_patterns: exclude_patterns,
+      site_paths: build_site_paths(site, exclude_patterns),
+      # Lazy cache: `site_path -> [decoded_segs, encoded_segs]`.
+      # Decoded drives the LCP walk against filesystem-derived
+      # `file_segs`; encoded is what gets emitted in the output URL.
+      seg_cache: {},
+      # Lazy cache: `"#{file_dir}\x00#{raw}" -> final_rel_url` (or
+      # nil for unresolvable). Each unique `(file_dir, raw)` pair is
+      # resolved exactly once across the build. Shared between the
+      # absolute-URL and page-relative dispatches inside the combined
+      # HTML pass -- the cache keys are disjoint because absolute
+      # raws start with `/` and relative ones don't.
+      result_cache: {},
+      rewritten_html: 0,
+      rewritten_css: 0,
+      copied_files: 0,
+      excluded_files: 0,
+      unresolved: 0,
+      # Cumulative time-in-Offlinify-hooks. Tracks self-time across
+      # setup/process_page/finish so the reported number reflects
+      # Offlinify's work alone -- not the wall-clock between
+      # pre_render and post_write (which includes Jekyll's render
+      # and write phases between our hooks).
+      cumulative_ms: 0.0,
+    }
+
+    wipe_out_dest_contents(out_dest)
+    @state[:cumulative_ms] += (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
+  end
+
+  # Normalise the configured baseurl to either empty string or
+  # `/segment...` with no trailing slash, matching the form
+  # `relative_url` actually prepends to URLs in rendered HTML.
+  # `relative_url` strips a configured trailing slash and adds a
+  # leading one; we mirror that so the offline rewrite handles
+  # both configurations.
+  def self.normalize_baseurl(raw_baseurl)
+    baseurl = (raw_baseurl || "").to_s.sub(%r{/+\z}, "")
+    baseurl = "/#{baseurl}" if !baseurl.empty? && !baseurl.start_with?("/")
+    baseurl
+  end
+
+  # Build the `site_paths` Set from Jekyll's in-memory page set
+  # (pages + static_files + documents). Each item's `destination(dest)`
+  # returns the absolute file path it will be written to; converting
+  # to site-rooted forward-slash form yields the same keys the older
+  # filesystem walk produced (e.g. `/tB/Core/Const.html`). Keys are
+  # decoded -- they mirror filesystem names, so `Form Designer.html`
+  # goes in literally, not `Form%20Designer.html`.
+  def self.build_site_paths(site, exclude_patterns)
+    paths = Set.new
+    dest_pn = Pathname.new(site.dest)
+    items = site.pages + site.static_files + site.documents
+    items.each do |item|
+      dest = item.destination(site.dest)
+      rel = Pathname.new(dest).relative_path_from(dest_pn).to_s.tr("\\", "/")
+      next if offline_excluded?(rel, exclude_patterns)
+      paths << "/#{rel}"
+    end
+    paths
+  end
+
+  # Wipe the offline output tree but keep the `_site-offline/`
+  # directory itself in place. Deleting and recreating the directory
+  # surfaces in jekyll-watch as a bare `_site-offline` change event
+  # -- no trailing slash, since the directory was momentarily absent
+  # at notification time -- which the exclude entry's auto-generated
+  # `_site\-offline\/` regex does not match. Result: an infinite
+  # rebuild loop on `jekyll serve`. Cleaning contents in place keeps
+  # every event under `_site-offline/...` where the exclude matches.
+  def self.wipe_out_dest_contents(out_dest)
     if Dir.exist?(out_dest)
       Dir.glob(File.join(out_dest, "*"), File::FNM_DOTMATCH).each do |entry|
         basename = File.basename(entry)
@@ -388,103 +502,112 @@ def self.run(site, src_dest, out_dest)
     else
       FileUtils.mkdir_p(out_dest)
     end
+  end
 
-    # Pre-walk the source tree once and bucket every file under its
-    # site-rooted forward-slash path (decoded -- the keys mirror
-    # filesystem names, so `/Tutorials/CustomControls/Form Designer.html`
-    # not `Form%20Designer`). Resolution in compute_relative becomes an
-    # O(1) Set probe per candidate, instead of 2-3 File.file? syscalls
-    # each (very slow on Windows).
-    site_paths = Set.new
-    src_pn = Pathname.new(src_dest)
-    Dir.glob(File.join(src_dest, "**", "*"), File::FNM_DOTMATCH).each do |p|
-      next unless File.file?(p)
-      rel = Pathname.new(p).relative_path_from(src_pn).to_s.tr("\\", "/")
-      next if offline_excluded?(rel, exclude_patterns)
-      site_paths << "/#{rel}"
-    end
-
-    # Lazy global cache: `site_path -> [decoded_segs, encoded_segs]`.
-    # Filled on first reference. Decoded segments drive the LCP walk
-    # (compared against filesystem-derived `file_segs`); encoded
-    # segments are what we emit in the output URL.
-    seg_cache = {}
-
-    # Lazy global cache: `"#{file_dir}\x00#{raw}" -> final_rel_url`
-    # (or nil for unresolvable). Subsumes step 1 (raw -> site_path)
-    # and step 2 (site_path -> page-relative URL) so each unique
-    # `(file_dir, raw)` pair is computed exactly once across the build.
-    result_cache = {}
-
-    rewritten_html = 0
-    rewritten_css  = 0
-    copied_assets  = 0
-    excluded_files = 0
-    unresolved = 0
-
-    Dir.glob(File.join(src_dest, "**", "*"), File::FNM_DOTMATCH).each do |src_path|
-      next unless File.file?(src_path)
-      rel = src_path[src_dest.length + 1..]
-
-      if offline_excluded?(rel.tr("\\", "/"), exclude_patterns)
-        # src_dest is _site/, out_dest is _site-offline/. Skipping the
-        # file means it never gets copied, leaving the online _site/
-        # untouched.
-        excluded_files += 1
-        next
-      end
-
-      out_path = File.join(out_dest, rel)
+  # `:pages, :post_render` / `:documents, :post_render` hook entry.
+  # Called once per rendered page or document. Reads `page.output`
+  # in memory and writes the offline copy straight to
+  # `_site-offline/<rel>` -- no detour through `_site/`. Dispatches
+  # on output extension: .html runs the combined URL rewrite + the
+  # search-setup injection; .css runs the url() rewrite; anything
+  # else (XML, JSON, etc.) is written verbatim.
+  def self.process_page(page)
+    return unless @state
+    start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    # page.destination returns the absolute file path Jekyll will
+    # write (joining site.dest with the URL-unescaped url). Strip
+    # the dest prefix with a plain string slice rather than a
+    # Pathname round-trip -- Pathname#relative_path_from is roughly
+    # 2ms per call on Windows and would dominate per-page cost on a
+    # 1000+ page build.
+    dest_path = page.destination(@state[:dest]).tr("\\", "/")
+    rel = dest_path[(@state[:dest_root_fs].length + 1)..]
+
+    if offline_excluded?(rel, @state[:exclude_patterns])
+      @state[:excluded_files] += 1
+    elsif page.class.name == "JekyllRedirectFrom::RedirectPage"
+      # jekyll-redirect-from stubs aren't useful in the offline tree.
+      # Their meta-refresh / canonical link / fallback `<a>` all point
+      # at the live online URL (e.g. `https://docs.twinbasic.com/...`
+      # when `site.url` is set), so following one offline requires
+      # network access and lands on the live site -- defeating the
+      # offline scenario. And nothing inside the offline tree links
+      # at a redirect_from URL: internal markdown links resolve to
+      # the canonical permalink. The stubs are unreachable from
+      # within `_site-offline/` and useless if reached. Drop them.
+      #
+      # Class-name string check rather than `is_a?` so the plugin
+      # still loads if jekyll-redirect-from is removed.
+      @state[:excluded_files] += 1
+    else
+      out_path = File.join(@state[:out_dest], rel)
+      file_dir = File.dirname(out_path)
+      file_segs = file_dir_segs_from_rel(rel)
 
-      case File.extname(src_path).downcase
+      case File.extname(dest_path).downcase
       when ".html"
-        content = File.binread(src_path)
-        file_dir  = File.dirname(out_path)
-        file_segs = file_dir_segs_from_rel(rel)
+        content = page.output.dup
         code_ranges = code_block_ranges(content)
-        changed_url, misses = rewrite_html!(content, file_dir, file_segs, site_paths, seg_cache, result_cache, baseurl, code_ranges)
-        unresolved += misses
-        changed_search = inject_search_setup!(content, file_segs)
-        if changed_url || changed_search
-          FileUtils.mkdir_p(File.dirname(out_path))
-          File.binwrite(out_path, content)
-          rewritten_html += 1
-        else
-          copy_asset!(src_path, out_path)
-          copied_assets += 1
-        end
+        _changed, misses = rewrite_html!(content, file_dir, file_segs, @state[:site_paths], @state[:seg_cache], @state[:result_cache], @state[:baseurl], code_ranges)
+        @state[:unresolved] += misses
+        inject_search_setup!(content, file_segs)
+        FileUtils.mkdir_p(file_dir)
+        File.binwrite(out_path, content)
+        @state[:rewritten_html] += 1
       when ".css"
-        content = File.binread(src_path)
-        file_dir  = File.dirname(out_path)
-        file_segs = file_dir_segs_from_rel(rel)
-        changed, misses = rewrite_css!(content, file_dir, file_segs, site_paths, seg_cache, result_cache, baseurl)
-        unresolved += misses
-        if changed
-          FileUtils.mkdir_p(File.dirname(out_path))
-          File.binwrite(out_path, content)
-          rewritten_css += 1
-        else
-          copy_asset!(src_path, out_path)
-          copied_assets += 1
-        end
+        content = page.output.dup
+        _changed, misses = rewrite_css!(content, file_dir, file_segs, @state[:site_paths], @state[:seg_cache], @state[:result_cache], @state[:baseurl])
+        @state[:unresolved] += misses
+        FileUtils.mkdir_p(file_dir)
+        File.binwrite(out_path, content)
+        @state[:rewritten_css] += 1
       else
-        copy_asset!(src_path, out_path)
-        copied_assets += 1
+        FileUtils.mkdir_p(file_dir)
+        File.binwrite(out_path, page.output)
+        @state[:copied_files] += 1
+      end
+    end
+
+    @state[:cumulative_ms] += (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
+  end
+
+  # `:site, :post_write` hook entry. Static files don't fire
+  # `:pages, :post_render`, so we copy them from `_site/` here, after
+  # Jekyll's WRITE has populated it. Also patches just-the-docs.js
+  # and generates search-data.js from the search index Jekyll wrote
+  # during the per-page phase. Logs the summary and elapsed time
+  # and clears `@state`.
+  def self.finish(site)
+    return unless @state
+    start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    site.static_files.each do |sf|
+      dest_path = sf.destination(@state[:dest]).tr("\\", "/")
+      rel = dest_path[(@state[:dest_root_fs].length + 1)..]
+      if offline_excluded?(rel, @state[:exclude_patterns])
+        @state[:excluded_files] += 1
+        next
       end
+      out_path = File.join(@state[:out_dest], rel)
+      copy_asset!(dest_path, out_path)
+      @state[:copied_files] += 1
     end
 
-    js_patches = patch_jtd_js!(out_dest)
-    search_data_built = build_search_data_js!(out_dest)
+    js_patches = patch_jtd_js!(@state[:out_dest])
+    search_data_built = build_search_data_js!(@state[:out_dest])
 
-    summary = "rewrote #{rewritten_html} HTML and #{rewritten_css} CSS file(s), copied #{copied_assets} asset(s)"
-    summary += ", excluded #{excluded_files} file(s)" if excluded_files.positive?
-    summary += " (#{unresolved} unresolved link(s) left as-is)" if unresolved.positive?
+    @state[:cumulative_ms] += (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
+
+    summary = "rewrote #{@state[:rewritten_html]} HTML and #{@state[:rewritten_css]} CSS file(s), copied #{@state[:copied_files]} asset(s)"
+    summary += ", excluded #{@state[:excluded_files]} file(s)" if @state[:excluded_files].positive?
+    summary += " (#{@state[:unresolved]} unresolved link(s) left as-is)" if @state[:unresolved].positive?
     Jekyll.logger.info "Offlinify:", summary
     Jekyll.logger.info "Offlinify:", "patched just-the-docs.js (#{js_patches.join(", ")})" unless js_patches.empty?
     Jekyll.logger.info "Offlinify:", "wrote #{SEARCH_DATA_JS_REL} (#{search_data_built} bytes)" if search_data_built
+    Jekyll.logger.info "Offlinify:", "Offlinifier ran in #{@state[:cumulative_ms].round(0)}ms."
 
-    elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(0)
-    Jekyll.logger.info "Offlinify:", "Offlinifier ran in #{elapsed_ms}ms."
+    @state = nil
   end
 
   # Copy a file from src to out, creating intermediate directories.
@@ -836,9 +959,20 @@ def self.decode(path)
   end
 end
 
+Jekyll::Hooks.register :site, :pre_render do |site|
+  next unless site.config["also_build_offline"]
+  Offlinify.setup(site)
+end
+
+Jekyll::Hooks.register :pages, :post_render do |page|
+  Offlinify.process_page(page)
+end
+
+Jekyll::Hooks.register :documents, :post_render do |doc|
+  Offlinify.process_page(doc)
+end
+
 Jekyll::Hooks.register :site, :post_write do |site|
   next unless site.config["also_build_offline"]
-  # site.dest is the online copy (`_site/`); produce the offline variant
-  # alongside it at `<site.dest>-offline` (`_site-offline/`).
-  Offlinify.run(site, site.dest, "#{site.dest}-offline")
+  Offlinify.finish(site)
 end

From 51576a830915a4ad70a25fb92b9563b629b8c645 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 17 May 2026 18:03:14 +0200
Subject: [PATCH 4/6] Offlinify redirect stubs that incorrectly pointed to the
 online site.

---
 docs/_plugins/offlinify.md | 12 ++++----
 docs/_plugins/offlinify.rb | 60 +++++++++++++++++++++++++++++++-------
 2 files changed, 56 insertions(+), 16 deletions(-)

diff --git a/docs/_plugins/offlinify.md b/docs/_plugins/offlinify.md
index f9176a4..e3cf6d1 100644
--- a/docs/_plugins/offlinify.md
+++ b/docs/_plugins/offlinify.md
@@ -74,7 +74,7 @@ For each page:
 
 2. **Check `offline_exclude`** (see [Exclude list](#exclude-list)). Matched files increment the `excluded_files` counter and skip the write.
 
-3. **Detect jekyll-redirect-from stubs** by class-name string check (`page.class.name == "JekyllRedirectFrom::RedirectPage"`). The redirect stubs aren't useful in the offline tree — their meta-refresh, canonical link, and fallback `<a>` all point at the live online URL (`https://docs.twinbasic.com/...` when `site.url` is set), so following one offline requires network access and lands on the live site rather than the local file. Skip the write; count them under `excluded_files`. The class-name string check is used rather than `is_a?` so the plugin still loads if jekyll-redirect-from is removed.
+3. **Detect jekyll-redirect-from stubs** by class-name string check (`page.class.name == "JekyllRedirectFrom::RedirectPage"`). The stubs are tiny HTML files whose meta-refresh, canonical link, `<script>location=`, and fallback `<a>` all reference an absolute `https://<site.url>/<path>` URL produced by `absolute_url`. Online these redirect to the canonical page; offline they would require network access and land on the live site rather than the local file — defeating the offline scenario. Rewrite each `<site.url><path>` occurrence to its resolved page-relative form via the same `compute_relative` the main HTML pass uses, then write the stub. Counted under `rewritten_redirects` in the summary log line. Some source pages (notably `Miscellaneous/Documentation Development.md`) intentionally link via `redirect_from` URLs as a stable-URL pattern, so the rewritten stubs let those source links navigate locally instead of failing. The class-name string check is used rather than `is_a?` so the plugin still loads if jekyll-redirect-from is removed. If `site.url` is unset (empty) the stub is written verbatim — the path-portion targets still resolve under lychee's offline check the same way the main HTML pass's link targets do.
 
 4. **Dispatch on output extension:**
    - `.html`: dup `page.output`, scan for code-block ranges, run the combined HTML URL rewrite (see [HTML URL rewriting](#html-url-rewriting)), inject the search-setup script tags, write.
@@ -265,9 +265,9 @@ The exclude check runs in two places:
 1. **Inside `build_site_paths` in `setup`**, so URL-resolution candidates can't point at an excluded target (a stray `<a href="/sitemap.xml">` in the source would simply fail to resolve, instead of resolving to a now-missing file).
 2. **Inside `process_page` and the static-file loop in `finish`**, where the write is skipped so the file never appears in `_site-offline/`.
 
-In addition to the pattern-based excludes, **jekyll-redirect-from stubs are unconditionally dropped** from the offline tree (detected by the `JekyllRedirectFrom::RedirectPage` class-name check in `process_page`). The stubs contain only a meta-refresh / canonical link / fallback `<a>`, all pointing at the live online URL — following one offline requires network access and lands on the live site, defeating the offline scenario. Source markdown should use the canonical URL directly rather than relying on the redirect; the strict lychee step in CI surfaces any source link that still goes through a redirect.
+In addition to the pattern-based excludes, **jekyll-redirect-from stubs get their absolute URLs rewritten** to page-relative form rather than being excluded (detected by the `JekyllRedirectFrom::RedirectPage` class-name check in `process_page`). The stubs contain only a meta-refresh / canonical link / `<script>location=` / fallback `<a>`, all referencing `https://<site.url>/<path>`. Left alone, following one offline would require network access and land on the live site. Each `<site.url><path>` occurrence is run through the same `compute_relative` the main HTML pass uses and replaced with the resolved relative path, so the stub navigates locally instead. The rewritten stubs are reachable from the offline tree, which matters for source pages (notably `Miscellaneous/Documentation Development.md`) that intentionally link via `redirect_from` URLs as a stable-URL pattern. Counted under `rewritten_redirects` in the summary log line, distinct from the pattern-matched `excluded_files`.
 
-The summary log line reports the count: `… excluded 294 file(s) …` (pattern-matched + redirect stubs combined).
+The summary log line reports both counts: `… rewrote N redirect stub(s) … excluded M file(s) …`.
 
 ## Caches
 
@@ -318,7 +318,7 @@ The plugin surfaces several conditions in its summary log lines:
 
 - **Missing `search-data.json`.** Silent — the search-data.js generation step is a no-op. The per-page script tag injection still runs, so each page will request `search-data.js` and the browser will log a 404. The patched `initSearch()` will hit its `window.SEARCH_DATA not found` branch and log a console message.
 
-- **Real broken links in markdown sources.** Caught by the strict lychee step in CI (or by `check.bat` locally). These don't surface in the offlinify summary because the rewrite passes correctly identify them as unresolvable and leave them alone — that's the right behavior, the source markdown needs fixing. Since jekyll-redirect-from stubs are dropped from the offline tree, any source markdown linking at a `redirect_from` URL surfaces as a broken offline link until the source link is updated to point at the canonical URL.
+- **Real broken links in markdown sources.** Caught by the strict lychee step in CI (or by `check.bat` locally). These don't surface in the offlinify summary because the rewrite passes correctly identify them as unresolvable and leave them alone — that's the right behavior, the source markdown needs fixing. Source markdown linking at a `redirect_from` URL is reachable in the offline tree (the redirect stub is rewritten to navigate locally), but a stub that itself references a missing target falls back to the original `https://<site.url>/...` URL and lychee will then surface it as broken — same right-thing-to-do behaviour.
 
 - **`_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).
 
@@ -330,7 +330,7 @@ The optimization story is captured in the commit history. Briefly:
 - **+ `site_paths` Set** (O(1) lookup): down to ~10 s, before further work.
 - **+ `result_cache`, `seg_cache`, manual LCP** (replaced `Pathname.relative_path_from` per match with a string-segment comparison): down to ~7 s as the site grew past 800 pages.
 - **+ combined HTML regex** (single gsub matching both absolute and page-relative URLs in one pass — eliminating the second full file scan and the interim re-scan of code-block ranges that used to sit between two separate passes): down to ~4 s. Roughly 40% off the HTML walk.
-- **+ per-page hook architecture** (`:pages, :post_render` consumes `page.output` in memory rather than re-reading the rendered HTML from `_site/` at `:site, :post_write`): the per-file `File.binread` is eliminated. Cumulative self-time across hooks is ~5-6 s on the current ~830-page site, dominated by per-page Jekyll hook dispatch overhead and the per-page `File.binwrite`. Skipping the ~290 jekyll-redirect-from stubs (see [Phase 2](#phase-2-process_page)) trims ~400 ms.
+- **+ per-page hook architecture** (`:pages, :post_render` consumes `page.output` in memory rather than re-reading the rendered HTML from `_site/` at `:site, :post_write`): the per-file `File.binread` is eliminated. Cumulative self-time across hooks is ~5-6 s on the current ~830-page site, dominated by per-page Jekyll hook dispatch overhead and the per-page `File.binwrite`. The ~290 jekyll-redirect-from stubs go through a much cheaper code path than the main HTML pass (a single regex over a few hundred bytes, no code-block scan, no search-setup injection) so they're a small slice of the total.
 
 The remaining cumulative time is mostly `File.binwrite` across ~830 HTML files (Windows file I/O on NTFS is the dominant cost) plus the regex pass over the SCSS-compiled `just-the-docs-combined.css`.
 
@@ -354,7 +354,7 @@ In source order in [`offlinify.rb`](offlinify.rb):
 - `normalize_baseurl(raw_baseurl)` — helper for `setup`. Coerces the configured baseurl to either empty string or `/segment...` with no trailing slash, matching the form `relative_url` actually prepends.
 - `build_site_paths(site, exclude_patterns)` — helper for `setup`. Iterates `site.pages + site.static_files + site.documents` and builds the URL Set from each item's `destination(site.dest)`, decoded and forward-slash-normalised.
 - `wipe_out_dest_contents(out_dest)` — helper for `setup`. Removes the offline tree contents while leaving the directory itself in place (see [Phase 1](#phase-1-setup)).
-- `process_page(page)` — `:pages, :post_render` and `:documents, :post_render` hook entry. Transforms `page.output` and writes the offline copy. Dispatches on output extension and on page class (skips jekyll-redirect-from stubs entirely).
+- `process_page(page)` — `:pages, :post_render` and `:documents, :post_render` hook entry. Transforms `page.output` and writes the offline copy. Dispatches on output extension and on page class (jekyll-redirect-from stubs get a dedicated branch that rewrites their absolute `<site.url>/<path>` URLs to page-relative form).
 - `finish(site)` — `:site, :post_write` hook entry. Copies static files from `_site/` to `_site-offline/`, patches just-the-docs.js, generates search-data.js, logs the summary, clears `@state`.
 - `rewrite_html!(content, file_dir, file_segs, site_paths, seg_cache, result_cache, baseurl, code_ranges)` — the combined HTML pass. One `gsub` per file over `HTML_COMBINED_RE`, dispatching on `raw.start_with?("/")`: absolute URLs go through `compute_relative`, page-relative URLs through `compute_rel_url`. Single cache lookup per match.
 - `rewrite_css!(content, file_dir, file_segs, site_paths, seg_cache, result_cache, baseurl)` — the CSS pass. One `gsub` per file over `CSS_URL_RE`, dispatched to `compute_relative` (CSS only carries absolute URLs in this codebase). No code-block handling — CSS has no equivalent concept.
diff --git a/docs/_plugins/offlinify.rb b/docs/_plugins/offlinify.rb
index 72132e0..2073841 100644
--- a/docs/_plugins/offlinify.rb
+++ b/docs/_plugins/offlinify.rb
@@ -422,6 +422,14 @@ def self.setup(site)
       dest_root_fs: site.dest.tr("\\", "/"),
       out_dest: out_dest,
       baseurl: normalize_baseurl(site.config["baseurl"]),
+      # `site.url` with any trailing slash stripped. Used by the
+      # redirect-stub branch in process_page to recognise and rewrite
+      # the absolute `<site.url><path>` URLs that jekyll-redirect-from
+      # bakes into each stub's meta-refresh, canonical link,
+      # `<script>location=`, and fallback `<a>`. Empty when `url:` is
+      # not configured -- the rewrite step short-circuits in that
+      # case and the stub is written verbatim.
+      site_url: site.config["url"].to_s.sub(%r{/+\z}, ""),
       exclude_patterns: exclude_patterns,
       site_paths: build_site_paths(site, exclude_patterns),
       # Lazy cache: `site_path -> [decoded_segs, encoded_segs]`.
@@ -437,6 +445,7 @@ def self.setup(site)
       result_cache: {},
       rewritten_html: 0,
       rewritten_css: 0,
+      rewritten_redirects: 0,
       copied_files: 0,
       excluded_files: 0,
       unresolved: 0,
@@ -527,19 +536,49 @@ def self.process_page(page)
     if offline_excluded?(rel, @state[:exclude_patterns])
       @state[:excluded_files] += 1
     elsif page.class.name == "JekyllRedirectFrom::RedirectPage"
-      # jekyll-redirect-from stubs aren't useful in the offline tree.
-      # Their meta-refresh / canonical link / fallback `<a>` all point
-      # at the live online URL (e.g. `https://docs.twinbasic.com/...`
-      # when `site.url` is set), so following one offline requires
-      # network access and lands on the live site -- defeating the
-      # offline scenario. And nothing inside the offline tree links
-      # at a redirect_from URL: internal markdown links resolve to
-      # the canonical permalink. The stubs are unreachable from
-      # within `_site-offline/` and useless if reached. Drop them.
+      # jekyll-redirect-from stubs are tiny HTML files whose
+      # meta-refresh, canonical link, `<script>location=`, and
+      # fallback `<a>` all reference an absolute
+      # `https://<site.url>/<path>` URL produced by `absolute_url`.
+      # Online these redirect to the canonical page; offline they
+      # would require network access and land on the live site,
+      # defeating the offline scenario. Some source pages (notably
+      # `Miscellaneous/Documentation Development.md`) intentionally
+      # link via redirect_from URLs as a stable-URL pattern, so the
+      # stubs need to be reachable from inside `_site-offline/`.
+      #
+      # Rewrite each `<site_url><path>` occurrence to its resolved
+      # page-relative form via the same `compute_relative` the main
+      # HTML pass uses. Unresolved matches fall back to the original
+      # absolute URL -- lychee will then flag the source as broken,
+      # which is the right behaviour for a real bug. If `site.url`
+      # is unset (empty), write the stub verbatim: lychee against
+      # _site-offline/ will still find the path-portion targets in
+      # the same way the main HTML pass does, so the stub passes
+      # link-check even though it won't navigate locally.
       #
       # Class-name string check rather than `is_a?` so the plugin
       # still loads if jekyll-redirect-from is removed.
-      @state[:excluded_files] += 1
+      out_path = File.join(@state[:out_dest], rel)
+      file_dir = File.dirname(out_path)
+      content = page.output.dup
+      site_url = @state[:site_url]
+      unless site_url.empty?
+        file_segs = file_dir_segs_from_rel(rel)
+        prefix_re = /#{Regexp.escape(site_url)}(\/[^"' >]*)/
+        content = content.gsub(prefix_re) do
+          raw = Regexp.last_match(1)
+          cache_key = "#{file_dir}\x00#{raw}"
+          rel_url = @state[:result_cache].fetch(cache_key) do
+            @state[:result_cache][cache_key] =
+              compute_relative(raw, file_segs, @state[:site_paths], @state[:seg_cache], @state[:baseurl])
+          end
+          rel_url || "#{site_url}#{raw}"
+        end
+      end
+      FileUtils.mkdir_p(file_dir)
+      File.binwrite(out_path, content)
+      @state[:rewritten_redirects] += 1
     else
       out_path = File.join(@state[:out_dest], rel)
       file_dir = File.dirname(out_path)
@@ -600,6 +639,7 @@ def self.finish(site)
     @state[:cumulative_ms] += (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
 
     summary = "rewrote #{@state[:rewritten_html]} HTML and #{@state[:rewritten_css]} CSS file(s), copied #{@state[:copied_files]} asset(s)"
+    summary += ", rewrote #{@state[:rewritten_redirects]} redirect stub(s)" if @state[:rewritten_redirects].positive?
     summary += ", excluded #{@state[:excluded_files]} file(s)" if @state[:excluded_files].positive?
     summary += " (#{@state[:unresolved]} unresolved link(s) left as-is)" if @state[:unresolved].positive?
     Jekyll.logger.info "Offlinify:", summary

From a25006613b030acc41aab9a82b8eb47e62ae4352 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 17 May 2026 18:37:25 +0200
Subject: [PATCH 5/6] Fix a typo in an online link.

---
 docs/Miscellaneous/FAQs.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/Miscellaneous/FAQs.md b/docs/Miscellaneous/FAQs.md
index 8124044..e8bb7f9 100644
--- a/docs/Miscellaneous/FAQs.md
+++ b/docs/Miscellaneous/FAQs.md
@@ -69,7 +69,7 @@ For a full list of all the new features available right now, see the Wiki articl
 {: #to-learn-more }
 [twinBASIC Home Page](https://twinbasic.com)
 
-twinBASIC GitHub: [Main section](https://github.com/twinbasic/twinbasic) \| [Issues](https://github.com/twinbasic/twinbasic/issues) \| [Discussions](https://github.com/twinbasic/twinbasic/discussions) \| [Language Design](https://github.com/twinbasic/lang-design) \| [ Language Specification](https://github.com/twinbasic/lang-spec) \| [Documentation](https://docs.twinbasic.comi)
+twinBASIC GitHub: [Main section](https://github.com/twinbasic/twinbasic) \| [Issues](https://github.com/twinbasic/twinbasic/issues) \| [Discussions](https://github.com/twinbasic/twinbasic/discussions) \| [Language Design](https://github.com/twinbasic/lang-design) \| [ Language Specification](https://github.com/twinbasic/lang-spec) \| [Documentation](https://docs.twinbasic.com)
 
 [twinBASIC Discord](https://discord.gg/UaW9GgKKuE)
 

From 1e360a82ca31b76bd07464570168c457b791f938 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 17 May 2026 18:38:36 +0200
Subject: [PATCH 6/6] Have the offlinifier also translate the redirect stubs.

---
 .../Documentation Development.md              |  2 +-
 docs/_plugins/offlinify.md                    | 16 ++-
 docs/_plugins/offlinify.rb                    | 48 +++++++++
 docs/check.bat                                | 23 ++++-
 scripts/check_offline_live_links.py           | 97 +++++++++++++++++++
 5 files changed, 178 insertions(+), 8 deletions(-)
 create mode 100644 scripts/check_offline_live_links.py

diff --git a/docs/Miscellaneous/Documentation Development.md b/docs/Miscellaneous/Documentation Development.md
index 59a6735..6105eac 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 [Lychee](https://github.com/lycheeverse/lychee) in offline mode against the built `_site/`.
+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.
 
 ### Building and Local Serving
 
diff --git a/docs/_plugins/offlinify.md b/docs/_plugins/offlinify.md
index e3cf6d1..979afe7 100644
--- a/docs/_plugins/offlinify.md
+++ b/docs/_plugins/offlinify.md
@@ -77,7 +77,7 @@ For each page:
 3. **Detect jekyll-redirect-from stubs** by class-name string check (`page.class.name == "JekyllRedirectFrom::RedirectPage"`). The stubs are tiny HTML files whose meta-refresh, canonical link, `<script>location=`, and fallback `<a>` all reference an absolute `https://<site.url>/<path>` URL produced by `absolute_url`. Online these redirect to the canonical page; offline they would require network access and land on the live site rather than the local file — defeating the offline scenario. Rewrite each `<site.url><path>` occurrence to its resolved page-relative form via the same `compute_relative` the main HTML pass uses, then write the stub. Counted under `rewritten_redirects` in the summary log line. Some source pages (notably `Miscellaneous/Documentation Development.md`) intentionally link via `redirect_from` URLs as a stable-URL pattern, so the rewritten stubs let those source links navigate locally instead of failing. The class-name string check is used rather than `is_a?` so the plugin still loads if jekyll-redirect-from is removed. If `site.url` is unset (empty) the stub is written verbatim — the path-portion targets still resolve under lychee's offline check the same way the main HTML pass's link targets do.
 
 4. **Dispatch on output extension:**
-   - `.html`: dup `page.output`, scan for code-block ranges, run the combined HTML URL rewrite (see [HTML URL rewriting](#html-url-rewriting)), inject the search-setup script tags, write.
+   - `.html`: dup `page.output`, strip the jekyll-seo-tag block (see [SEO block stripping](#seo-block-stripping)), scan for code-block ranges, run the combined HTML URL rewrite (see [HTML URL rewriting](#html-url-rewriting)), inject the search-setup script tags, write.
    - `.css`: dup `page.output`, run the `url()` rewrite (see [CSS `url()` rewriting](#css-url-rewriting)), write.
    - Anything else (XML feeds, JSON, etc.): write `page.output` verbatim.
 
@@ -99,6 +99,14 @@ Fires at `:site, :post_write` — once after Jekyll's WRITE phase has populated
 
 ## Transformation passes
 
+### SEO block stripping
+
+The jekyll-seo-tag plugin emits a ~900-byte block at the top of every page's `<head>`, bracketed by `<!-- Begin Jekyll SEO tag vX.Y.Z -->` and `<!-- End Jekyll SEO tag -->` comments. Inside live a `<title>`, a generator tag, OpenGraph and Twitter Card meta, a `<link rel="canonical">` pointing at the live site, and a JSON-LD structured-data `<script>`. All of it exists for search-engine crawlers and social-media link previewers that never see `_site-offline/`.
+
+The whole block is stripped, except the `<title>` (the browser tab label, the only thing in the block a local reader actually uses). The bracketing comments go away too. On the current ~830-page site, the strip saves roughly 750 KB across the offline tree and removes three of the four `https://docs.twinbasic.com` references each page would otherwise contain (the fourth, the JSON-LD `"url"` field, is also inside the SEO block).
+
+Runs first in the `.html` branch of `process_page` so the URL rewrite isn't doing work on URLs we're about to delete, and so the code-block scan's byte offsets are valid against the post-strip content.
+
 ### HTML URL rewriting
 
 A single combined regex matches both absolute and page-relative URLs in `href`/`src` attributes:
@@ -292,7 +300,8 @@ 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` | Dual lychee — strict on `_site-offline/`, permissive (`--fallback-extensions html`) on `_site/`. |
+| `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/.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. |
 
@@ -322,6 +331,8 @@ 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.
+
 ## Performance
 
 The optimization story is captured in the commit history. Briefly:
@@ -359,6 +370,7 @@ In source order in [`offlinify.rb`](offlinify.rb):
 - `rewrite_html!(content, file_dir, file_segs, site_paths, seg_cache, result_cache, baseurl, code_ranges)` — the combined HTML pass. One `gsub` per file over `HTML_COMBINED_RE`, dispatching on `raw.start_with?("/")`: absolute URLs go through `compute_relative`, page-relative URLs through `compute_rel_url`. Single cache lookup per match.
 - `rewrite_css!(content, file_dir, file_segs, site_paths, seg_cache, result_cache, baseurl)` — the CSS pass. One `gsub` per file over `CSS_URL_RE`, dispatched to `compute_relative` (CSS only carries absolute URLs in this codebase). No code-block handling — CSS has no equivalent concept.
 - `inject_search_setup!(content, file_segs)` — the second HTML transformation. Single regex substitution per file: finds the just-the-docs.js script tag and prepends the two new ones.
+- `strip_seo!(content)` — removes the jekyll-seo-tag plugin's output block from a page's `<head>`, keeping only the `<title>` tag. Runs first in the `.html` branch of `process_page` so the URL rewrite and code-block scan see the post-strip content.
 - `compute_relative(raw, file_segs, site_paths, seg_cache, baseurl)` — the absolute-URL resolver. Strip baseurl, probe candidates, compute LCP, return final URL.
 - `compute_rel_url(raw, file_segs, site_paths)` — the page-relative-URL resolver. Normalise against the current page's dir, probe candidates, return original raw plus matching suffix.
 - `patch_jtd_js!(out_dest)` — does the `navLink()` and `initSearch()` body substitutions.
diff --git a/docs/_plugins/offlinify.rb b/docs/_plugins/offlinify.rb
index 2073841..36c07b1 100644
--- a/docs/_plugins/offlinify.rb
+++ b/docs/_plugins/offlinify.rb
@@ -211,6 +211,24 @@ module Offlinify
   # percent-encoded byte-by-byte.
   PATH_SAFE_RE = /[^A-Za-z0-9\-_.~!$&'()*+,;=:@]/.freeze
 
+  # Matches the jekyll-seo-tag plugin's output, bracketed by the
+  # `Begin Jekyll SEO tag vX.Y.Z` / `End Jekyll SEO tag` comments
+  # the plugin emits unconditionally. Inside the block live a
+  # `<title>`, generator/OpenGraph/Twitter-Card meta tags, a
+  # `<link rel="canonical">` pointing at the live site, and a
+  # JSON-LD structured-data `<script>`. The whole block is ~900
+  # bytes per page; the contents do nothing offline (search-engine
+  # crawlers and social-media link previewers never see
+  # `_site-offline/`) so all but the `<title>` (the browser tab
+  # label) is stripped. The block is single-line in just-the-docs's
+  # rendered output but the regex uses `.*?` with multiline mode
+  # in case future theme versions reformat it.
+  SEO_BLOCK_RE = /<!-- Begin Jekyll SEO tag.*?<!-- End Jekyll SEO tag -->/m.freeze
+
+  # Matches the `<title>...</title>` tag inside the SEO block,
+  # preserved verbatim into the stripped output.
+  TITLE_RE = /<title>.*?<\/title>/m.freeze
+
   # Path of the just-the-docs JS file relative to the site root.
   JTD_JS_REL = "assets/js/just-the-docs.js"
 
@@ -446,6 +464,7 @@ def self.setup(site)
       rewritten_html: 0,
       rewritten_css: 0,
       rewritten_redirects: 0,
+      seo_stripped: 0,
       copied_files: 0,
       excluded_files: 0,
       unresolved: 0,
@@ -587,6 +606,7 @@ def self.process_page(page)
       case File.extname(dest_path).downcase
       when ".html"
         content = page.output.dup
+        @state[:seo_stripped] += 1 if strip_seo!(content)
         code_ranges = code_block_ranges(content)
         _changed, misses = rewrite_html!(content, file_dir, file_segs, @state[:site_paths], @state[:seg_cache], @state[:result_cache], @state[:baseurl], code_ranges)
         @state[:unresolved] += misses
@@ -640,6 +660,7 @@ def self.finish(site)
 
     summary = "rewrote #{@state[:rewritten_html]} HTML and #{@state[:rewritten_css]} CSS file(s), copied #{@state[:copied_files]} asset(s)"
     summary += ", rewrote #{@state[:rewritten_redirects]} redirect stub(s)" if @state[:rewritten_redirects].positive?
+    summary += ", stripped SEO block from #{@state[:seo_stripped]} page(s)" if @state[:seo_stripped].positive?
     summary += ", excluded #{@state[:excluded_files]} file(s)" if @state[:excluded_files].positive?
     summary += " (#{@state[:unresolved]} unresolved link(s) left as-is)" if @state[:unresolved].positive?
     Jekyll.logger.info "Offlinify:", summary
@@ -733,6 +754,33 @@ def self.inject_search_setup!(content, file_segs)
     true
   end
 
+  # Strip the jekyll-seo-tag plugin's output block, keeping only the
+  # `<title>` tag (the browser tab label). The block is ~900 bytes
+  # per page and the rest -- generator tag, OpenGraph/Twitter Card
+  # meta, canonical link pointing at the live site, JSON-LD
+  # structured data -- exists for search-engine crawlers and
+  # social-media link previewers that never see `_site-offline/`.
+  # Stripping also removes ~3 of the `https://docs.twinbasic.com`
+  # references per page that would otherwise need to be carved
+  # around by any "no live-site links" check.
+  #
+  # Runs before the URL rewrite so the rewrite isn't doing work on
+  # URLs we're about to delete, and before the code-block scan so
+  # the byte offsets it produces are valid against the post-strip
+  # content. Returns true when the strip happened, false when the
+  # block wasn't found (e.g. a page without the layout, or a future
+  # build where the plugin is removed).
+  def self.strip_seo!(content)
+    return false unless content.include?("<!-- Begin Jekyll SEO tag")
+    new_content = content.sub(SEO_BLOCK_RE) do |block|
+      title = block.match(TITLE_RE)
+      title ? title[0] : ""
+    end
+    return false if new_content == content
+    content.replace(new_content)
+    true
+  end
+
   # Convert the rendered `assets/js/search-data.json` into a sibling
   # `assets/js/search-data.js` that assigns the data to a global. The
   # JS file is loaded as a `<script src=>` from each page (see
diff --git a/docs/check.bat b/docs/check.bat
index 358df2d..6d19e3b 100644
--- a/docs/check.bat
+++ b/docs/check.bat
@@ -1,4 +1,5 @@
-@rem Use lychee to check the links in both build outputs.
+@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
@@ -10,10 +11,17 @@
 @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 Both checks always run so you see all errors in one pass; the script
-@rem exits non-zero if either fails (online failure takes precedence in
-@rem the reported code).
+@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) ...
@@ -28,5 +36,10 @@
 @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%
-@exit /b %EXIT2%
+@if %EXIT2% NEQ 0 exit /b %EXIT2%
+@exit /b %EXIT3%
diff --git a/scripts/check_offline_live_links.py b/scripts/check_offline_live_links.py
new file mode 100644
index 0000000..c9fb030
--- /dev/null
+++ b/scripts/check_offline_live_links.py
@@ -0,0 +1,97 @@
+"""
+Scan docs/_site-offline/ for any https://docs.twinbasic.com/<path>
+reference outside of <code> / <pre> blocks. Exit 1 if any found,
+0 otherwise.
+
+Run by docs/check.bat after the offline lychee pass. After
+_plugins/offlinify.rb's SEO-block strip, no live-site references
+should remain except:
+
+  * Sample URLs inside <code> / <pre> blocks (tutorial code that
+    legitimately shows live URLs as data, e.g. the VBRUN.Hyperlink
+    `NavigateTo "https://docs.twinbasic.com/"` example). Skipped
+    via the same code-block shape offlinify uses for its URL
+    rewrite.
+  * The bare root URL `https://docs.twinbasic.com` or
+    `https://docs.twinbasic.com/` -- intentional "go to the live
+    docs site" links (e.g. the Documentation entry in the FAQ
+    resource list). Skipped via the tail check below.
+
+Anything deeper (`https://docs.twinbasic.com/tB/Core/Const`,
+`https://docs.twinbasic.comi`, ...) is flagged: in the offline
+copy those navigate back to the live site, undermining the local
+read; in source they should be a relative link or a /tB/...
+permalink that resolves locally.
+
+Run from anywhere:
+    python scripts/check_offline_live_links.py
+"""
+
+import re
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+REPO_ROOT = SCRIPT_DIR.parent
+OFFLINE_TREE = REPO_ROOT / "docs" / "_site-offline"
+
+# Matches a <code>...</code> or <pre>...</pre> block. Same shape as
+# _plugins/offlinify.rb CODE_BLOCK_RE so sample URLs in tutorial
+# code are skipped here too.
+CODE_BLOCK_RE = re.compile(r"<(code|pre)\b[^>]*>.*?</\1>", re.DOTALL)
+
+# Captures the trailing path/typo characters after the domain. An
+# empty tail or `/` means the bare root URL (intentional). Anything
+# else is a deep link or a typo (`.comi`, `.com/tB/...`).
+LIVE_LINK_RE = re.compile(r"https://docs\.twinbasic\.com(?P<tail>[^\s\"'<>]*)")
+
+
+def main() -> int:
+    if not OFFLINE_TREE.is_dir():
+        print(
+            f"_site-offline/ not found at {OFFLINE_TREE} -- run docs/build.bat first."
+        )
+        return 2
+
+    hits = []
+    for html in sorted(OFFLINE_TREE.rglob("*.html")):
+        content = html.read_text(encoding="utf-8")
+        link_matches = list(LIVE_LINK_RE.finditer(content))
+        if not link_matches:
+            continue
+        code_ranges = [(m.start(), m.end()) for m in CODE_BLOCK_RE.finditer(content)]
+        for m in link_matches:
+            tail = m.group("tail")
+            if tail == "" or tail == "/":
+                continue
+            if any(s <= m.start() < e for s, e in code_ranges):
+                continue
+            line_num = content.count("\n", 0, m.start()) + 1
+            start = max(0, m.start() - 60)
+            end = min(len(content), m.start() + 80)
+            snippet = re.sub(r"[\r\n]+", " ", content[start:end])
+            hits.append((html, line_num, snippet))
+
+    if hits:
+        print(
+            f"FAIL: {len(hits)} reference(s) to docs.twinbasic.com in "
+            f"_site-offline/ outside code blocks:"
+        )
+        for path, line_num, snippet in hits:
+            try:
+                rel = path.relative_to(REPO_ROOT)
+            except ValueError:
+                rel = path
+            print(f"  {rel}:{line_num}: ...{snippet}...")
+        print()
+        print(
+            "Update the source markdown to use a relative link or /tB/... "
+            "permalink instead."
+        )
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())