Fold book-chapter-body's replace chains into a Ruby filter.

Author: KubaO

WIP.md

@@ -499,7 +499,41 @@ Ranked by estimated wall-clock saving on the current Windows machine:
    | `Liquid::Variable#render` total | 10.05 s | 8.96 s | -1.09 s |
 
    The `BlockBody#render` / `Context#stack` / `Variable#render` drops reflect the eliminated `{%- assign -%}` / `{%- if -%}` blocks in head_seo.html (dropped from ~85 lines of Liquid logic to ~20 lines of straight output). The 128 remaining `markdownify` calls come from `book.html`'s part subtitle/intro (~24) and `book-chapter-body.html`'s per-chapter `chapter.content | markdownify` (~100 chapters whose content doesn't start with `<`); both candidates for a follow-up pass (see #3). New `Jekyll::SeoPrecompute#absolute_url` adds 0.44 s for 846 calls, replacing 1,675 filter calls that totalled 0.40 s -- essentially flat, but the absolute_url filter had its own per-build cache, so the swap is a wash on this axis. Output byte-identical to baseline (`diff -rq` clean on all three of `_site/`, `_site-offline/`, `_site-pdf/`).
-3. **`book-chapter-body.html` heading-shift + anchor-prefix `replace` chain → Ruby pass.** ~36 k replaces fold into one string rewrite. Smaller win (~0.3 s) but probably wants to land alongside #2 since both touch the same render path.
+3. **`book-chapter-body.html` heading-shift + anchor-prefix `replace` chain → Ruby pass. [LANDED]** Replaced the per-chapter chain of 0-3 heading-shift cascades (12 replaces each), the 12-pattern whitespace span wrapping, and the 13-replace anchor-id prefix pass with a single Liquid filter `book_chapter_transform` (`_plugins/book-chapter-transform.rb`). The filter takes the body, the site baseurl, a precomputed `heading_shift_n` (0-3, derived in Liquid from `skip_base_heading_shift` / `is_sub_page` / `extra_heading_shift`), and the chapter anchor; does all six passes in one method with no intermediate string allocations beyond what the regex engine produces internally. The dead `p1_search` / `p1_replace` / ... whitespace-pattern declarations were also removed from `book.html`'s prologue.
+
+   The single-pass heading shift (one regex bumping each level by N, capping at h7-stub for source levels above 6) is equivalent to N applications of the bottom-up cascade chain -- each source heading lands at `level + N` or `h7-stub` regardless of how many sequential passes the chain ran, since the cascade structure was an artifact of Liquid not having a bump-by-N primitive, not a semantic requirement.
+
+   Ruby-prof effect (post-SEO baseline vs post-chapter-transform):
+
+   | Metric | Before | After | Delta |
+   |---|---|---|---|
+   | Total instrumented wall | 36.90 s | 34.78 s | -2.12 s |
+   | `Liquid::Strainer#invoke` total | 5.97 s / 179,266 calls | 5.45 s / 122,397 calls | -0.52 s / -56,869 calls |
+   | `Liquid::StandardFilters#replace` calls | 87,991 | 48,577 | -39,414 |
+   | `Liquid::StandardFilters#replace` total | 0.58 s | 0.33 s | -0.25 s |
+   | new `BookChapterTransform#book_chapter_transform` | -- | 0.14 s / 718 calls | +0.14 s |
+   | `Liquid::BlockBody#render` total | 16.14 s | 14.43 s | -1.71 s |
+   | `Liquid::Context#stack` total | 15.50 s | 13.78 s | -1.71 s |
+   | `Liquid::Variable#render` total | 8.96 s | 7.82 s | -1.14 s |
+
+   The Liquid framework drops (`BlockBody#render`, `Context#stack`, `Variable#render`) again outweigh the filter-dispatch drop -- they capture the eliminated `{%- unless -%}` / `{%- if -%}` blocks plus the chained `| replace:` pipeline AST nodes. The new filter does ~190 µs per call across 718 invocations, covering the same work the eliminated 39 k Liquid replaces did. Output byte-identical to baseline (`diff -rq` clean on `_site/`, `_site-offline/`, `_site-pdf/`).
+
+#### Cumulative
+
+The three landed optimizations together (chapter precompute, SEO precompute, chapter-body transform) shrank ruby-prof's instrumented build wall from ~41.7 s (immediately post-html-compress baseline) down to 34.78 s -- about -7 s. The cumulative profile-table picture, comparing the post-html-compress baseline to the post-chapter-transform state:
+
+| Metric | Post-html-compress | Post-CT | Delta |
+|---|---|---|---|
+| Total instrumented wall | 39.30 s | 34.78 s | -4.52 s |
+| `Liquid::Strainer#invoke` total | 8.90 s / 191,365 calls | 5.45 s / 122,397 calls | -3.45 s / -68,968 calls |
+| `where_exp` calls | 37 | 0 | -37 |
+| `markdownify` calls | 1,802 | 128 | -1,674 |
+| `absolute_url` filter calls | 1,675 | 1 | -1,674 |
+| `replace` calls | 87,991 | 48,577 | -39,414 |
+| `Liquid::BlockBody#render` total | 18.38 s | 14.43 s | -3.95 s |
+| `Liquid::Context#stack` total | 18.19 s | 13.78 s | -4.41 s |
+
+What's left of the per-filter table is approximately what kramdown / Rouge actually parse and emit: the 128 remaining `markdownify` calls are the per-chapter `chapter.content | markdownify` in `book-chapter-body.html` plus `book.html`'s part subtitle / intro markdown. Each of those is unique input, so Jekyll's converter cache rarely hits and the kramdown parse itself dominates. Further savings on this axis would need either (a) reusing the already-rendered `_site/<page>.html` instead of re-parsing source markdown for the book, or (b) accepting kramdown's parse cost as the floor and looking elsewhere -- the next-biggest non-library hotspot is `Offlinify#rewrite_html!` at ~2 s of self-time, already heavily optimised (see `_plugins/offlinify.md`).
 
 ## Site integrity check
 

docs/_includes/book-chapter-body.html

@@ -99,168 +99,52 @@
 {%- endunless -%}
 
 {%- comment -%}
-  Strip the `src="<baseurl>/` prefix that `relative_url` injects when
-  `jekyll build --baseurl /<repo>` is passed (the CI deploy path uses
-  this for Pages project sites without a custom domain). With empty
-  baseurl the prefix collapses to `src="/`, matching the historical
-  leading-slash strip exactly. Once stripped, image paths inside
-  book.html are root-of-_site/-relative, which is what both pdfify's
-  source lookup and pagedjs's render-time fetch expect.
-{%- endcomment -%}
-{%- assign src_baseurl_strip = 'src="' | append: site.baseurl | append: '/' -%}
-
-{%- assign body = body
-    | replace: src_baseurl_strip, 'src="'
-    | replace: p1_search, p1_replace
-    | replace: p2_search, p2_replace
-    | replace: p3i12_search, p3i12_replace
-    | replace: p3i8_search,  p3i8_replace
-    | replace: p3i4_search,  p3i4_replace
-    | replace: p3_search,    p3_replace
-    | replace: p4i16_search, p4i16_replace
-    | replace: p4i12_search, p4i12_replace
-    | replace: p4i8_search,  p4i8_replace
-    | replace: p4i4_search,  p4i4_replace
-    | replace: p4_search,    p4_replace
-    | replace: '</span> <span', '</span><span class="w"> </span><span' -%}
-
-{%- assign stripped = body | strip -%}
-{%- unless stripped == "" -%}
-
-  {%- comment -%}
-    1.5a: heading depth shift. Source `# Title` becomes the chapter
-    title; in the book it lives one level below the part divider's
-    H1, so cascade every heading down by one. `<h6` becomes
-    `<h7-stub` since there's no real h7; in practice no chapter
-    content uses h5 or h6, so the stub never appears, but the rule
-    keeps the cascade consistent.
+  Body transformation: the `src="<baseurl>/` strip (so pagedjs's
+  render-time `<img>` fetches resolve against `_site/`), the 12
+  inter-span whitespace patterns (so pagedjs's page splitter doesn't
+  mash code-line tokens together at page breaks), the 0-3 heading
+  shift cascades (1.5a base, 1.6b sub-page, 1.9 chaptered-part
+  extra), and the per-heading anchor-id prefix injection all run in
+  one Ruby method via the `book_chapter_transform` filter (see
+  `_plugins/book-chapter-transform.rb` for the per-step rationale).
 
-    `skip_base_heading_shift` skips this pass entirely -- used when
-    the containing part or chapter divider is silent
-    (`no_outline_entry`) and the content should occupy the outline
-    level the divider would have used. 1.6b sub-page and 1.9 extra
-    shifts still cascade on top when their conditions hold.
-  {%- endcomment -%}
-  {%- unless include.skip_base_heading_shift -%}
-    {%- assign body = body
-        | replace: '<h6', '<h7-stub'
-        | replace: '</h6>', '</h7-stub>'
-        | replace: '<h5', '<h6'
-        | replace: '</h5>', '</h6>'
-        | replace: '<h4', '<h5'
-        | replace: '</h4>', '</h5>'
-        | replace: '<h3', '<h4'
-        | replace: '</h3>', '</h4>'
-        | replace: '<h2', '<h3'
-        | replace: '</h2>', '</h3>'
-        | replace: '<h1', '<h2'
-        | replace: '</h1>', '</h2>' -%}
-  {%- endunless -%}
+  `heading_shift_n` is the total number of cascade levels to apply,
+  precomputed in Liquid from the three flags. The plugin then bumps
+  every heading by exactly N in a single regex pass, capping at
+  `h7-stub` for source levels that exceed 6.
 
-  {%- comment -%}
-    1.6b: extra heading shift for sub-pages so they nest one level
-    deeper than their parent index in the PDF outline. A sub-page's
-    chapter title (source `#`) ends up as `<h3>` instead of `<h2>`,
-    sub-page sections as `<h4>` instead of `<h3>`, and so on. The
-    shift cascades through the same rule set; no real content reaches
-    h7-stub or beyond after this second pass.
-  {%- endcomment -%}
-  {%- if is_sub_page -%}
-    {%- assign body = body
-        | replace: '<h6', '<h7-stub'
-        | replace: '</h6>', '</h7-stub>'
-        | replace: '<h5', '<h6'
-        | replace: '</h5>', '</h6>'
-        | replace: '<h4', '<h5'
-        | replace: '</h4>', '</h5>'
-        | replace: '<h3', '<h4'
-        | replace: '</h3>', '</h4>'
-        | replace: '<h2', '<h3'
-        | replace: '</h2>', '</h3>' -%}
-  {%- endif -%}
+  `chapter_anchor` is the per-chapter id prefix derived from the
+  chapter URL (or supplied by the caller via
+  `chapter_anchor_override`). It's still computed in Liquid because
+  the article element below also reads it; the plugin just injects
+  it into every heading-id and `href="#..."` in the body.
+{%- endcomment -%}
+{%- assign heading_shift_n = 0 -%}
+{%- unless include.skip_base_heading_shift -%}{%- assign heading_shift_n = heading_shift_n | plus: 1 -%}{%- endunless -%}
+{%- if is_sub_page -%}{%- assign heading_shift_n = heading_shift_n | plus: 1 -%}{%- endif -%}
+{%- if include.extra_heading_shift -%}{%- assign heading_shift_n = heading_shift_n | plus: 1 -%}{%- endif -%}
 
-  {%- comment -%}
-    1.9 extra shift: chaptered-part chapters nest under the chapter-
-    divider's H2, so every chapter body needs one more level of
-    demotion on top of 1.5a (and 1.6b, if the chapter is a sub-page).
-    Without this, a class index's source H1 lands at H2 -- the same
-    outline depth as the chapter divider it should sit beneath -- so
-    `AmbientProperties class` appears as a sibling of `VBRUN Package`
-    rather than a child. The shift cascades through the same rule set;
-    real content stops at source-H4 (member sub-page section), which
-    after 1.5a + 1.6b + this pass ends up at h7-stub and is excluded
-    from the outline anyway.
-  {%- endcomment -%}
-  {%- if include.extra_heading_shift -%}
-    {%- assign body = body
-        | replace: '<h6', '<h7-stub'
-        | replace: '</h6>', '</h7-stub>'
-        | replace: '<h5', '<h6'
-        | replace: '</h5>', '</h6>'
-        | replace: '<h4', '<h5'
-        | replace: '</h4>', '</h5>'
-        | replace: '<h3', '<h4'
-        | replace: '</h3>', '</h4>'
-        | replace: '<h2', '<h3'
-        | replace: '</h2>', '</h3>' -%}
+{%- if include.chapter_anchor_override -%}
+  {%- assign chapter_anchor = include.chapter_anchor_override -%}
+{%- else -%}
+  {%- assign url_path = include.chapter.url | replace: '/', '-' -%}
+  {%- assign anchor_first_char = url_path | slice: 0, 1 -%}
+  {%- if anchor_first_char == '-' -%}
+    {%- assign url_len = url_path.size | minus: 1 -%}
+    {%- assign url_path = url_path | slice: 1, url_len -%}
   {%- endif -%}
-
-  {%- comment -%}
-    1.5b: chapter anchor + per-heading id uniqueness. Derive a stable
-    chapter anchor from the chapter URL (strip leading and trailing
-    slashes, replace inner slashes with dashes); the article element
-    carries the bare anchor as its id so Phase 2 cross-references can
-    target `#ch-<anchor>` and land at the chapter's first page. Every
-    heading id and intra-chapter `href="#..."` inside the chapter body
-    gets that anchor prepended so identical kramdown-generated slugs
-    (`see-also`, `example`, ...) don't collapse to one outline
-    destination.
-  {%- endcomment -%}
-  {%- if include.chapter_anchor_override -%}
-    {%- assign chapter_anchor = include.chapter_anchor_override -%}
-  {%- else -%}
-    {%- assign url_path = include.chapter.url | replace: '/', '-' -%}
-    {%- assign anchor_first_char = url_path | slice: 0, 1 -%}
-    {%- if anchor_first_char == '-' -%}
-      {%- assign url_len = url_path.size | minus: 1 -%}
-      {%- assign url_path = url_path | slice: 1, url_len -%}
-    {%- endif -%}
-    {%- assign anchor_last_char = url_path | slice: -1, 1 -%}
-    {%- if anchor_last_char == '-' -%}
-      {%- assign url_len = url_path.size | minus: 1 -%}
-      {%- assign url_path = url_path | slice: 0, url_len -%}
-    {%- endif -%}
-    {%- assign chapter_anchor = 'ch-' | append: url_path -%}
+  {%- assign anchor_last_char = url_path | slice: -1, 1 -%}
+  {%- if anchor_last_char == '-' -%}
+    {%- assign url_len = url_path.size | minus: 1 -%}
+    {%- assign url_path = url_path | slice: 0, url_len -%}
   {%- endif -%}
+  {%- assign chapter_anchor = 'ch-' | append: url_path -%}
+{%- endif -%}
 
-  {%- assign h2_class_prefix = '<h2 class="no_toc" id="' | append: chapter_anchor | append: '-' -%}
-  {%- assign h2_prefix       = '<h2 id="'                | append: chapter_anchor | append: '-' -%}
-  {%- assign h3_class_prefix = '<h3 class="no_toc" id="' | append: chapter_anchor | append: '-' -%}
-  {%- assign h3_prefix       = '<h3 id="'                | append: chapter_anchor | append: '-' -%}
-  {%- assign h4_class_prefix = '<h4 class="no_toc" id="' | append: chapter_anchor | append: '-' -%}
-  {%- assign h4_prefix       = '<h4 id="'                | append: chapter_anchor | append: '-' -%}
-  {%- assign h5_class_prefix = '<h5 class="no_toc" id="' | append: chapter_anchor | append: '-' -%}
-  {%- assign h5_prefix       = '<h5 id="'                | append: chapter_anchor | append: '-' -%}
-  {%- assign h6_class_prefix = '<h6 class="no_toc" id="' | append: chapter_anchor | append: '-' -%}
-  {%- assign h6_prefix       = '<h6 id="'                | append: chapter_anchor | append: '-' -%}
-  {%- assign h7_class_prefix = '<h7-stub class="no_toc" id="' | append: chapter_anchor | append: '-' -%}
-  {%- assign h7_prefix       = '<h7-stub id="'           | append: chapter_anchor | append: '-' -%}
-  {%- assign href_prefix     = 'href="#'                 | append: chapter_anchor | append: '-' -%}
+{%- assign body = body | book_chapter_transform: site.baseurl, heading_shift_n, chapter_anchor -%}
 
-  {%- assign body = body
-      | replace: '<h2 class="no_toc" id="',      h2_class_prefix
-      | replace: '<h2 id="',                     h2_prefix
-      | replace: '<h3 class="no_toc" id="',      h3_class_prefix
-      | replace: '<h3 id="',                     h3_prefix
-      | replace: '<h4 class="no_toc" id="',      h4_class_prefix
-      | replace: '<h4 id="',                     h4_prefix
-      | replace: '<h5 class="no_toc" id="',      h5_class_prefix
-      | replace: '<h5 id="',                     h5_prefix
-      | replace: '<h6 class="no_toc" id="',      h6_class_prefix
-      | replace: '<h6 id="',                     h6_prefix
-      | replace: '<h7-stub class="no_toc" id="', h7_class_prefix
-      | replace: '<h7-stub id="',                h7_prefix
-      | replace: 'href="#',                      href_prefix -%}
+{%- assign stripped = body | strip -%}
+{%- unless stripped == "" -%}
 
   {%- comment -%}
     Pick the article class and running-header text. When the caller