sync: fence-aware source expansion + the every-page single-h1 pin

Ported from dash-documentation-boilerplate 1.6.11 (30075d0).

_expand_source_directives was a whole-document regex sub, so a
`.. source::` written INSIDE a fence to teach the directive got
expanded like a real one — the injected ```python fence closes the
open one early, and from there the inlined file renders as markdown
with every `# comment` line becoming an <h1>. Machine lane only;
markdown2dash parses fences properly, so nothing looked wrong to a
human. Now a line walker that tracks the open marker (``` and ~~~)
and expands only at fence depth zero.

Prevention here: this fork's one directive (docs/reference_geo/geo.md,
inlining lib/policy_store.py) is at top level and no page teaches the
syntax inside a fence. The pin is what catches the day one does.

The sweep ran over all 11 non-admin pages and found no drift — one h1
each, distinct footer llms.txt links, "/" carrying the root link once.
It caught real content drift on leaflet and muicharts, so that is a
measurement rather than an assumption. Adapted: the template's inline
/admin skip is dead code here, the `pages` fixture already drops it.

Also refreshed the prerender-lane test's floor wording — it still said
2.6.1, which has been >=2.7.1 since Phase B.

602 passed / 1 skipped (flask), 599 passed / 4 skipped (fastapi).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: pip-install-python

DEVELOPMENT-LOG.md

@@ -483,3 +483,45 @@ dash-documentation-boilerplate `ab22fd7` (a commit this fork's first push
 prompted). Security updates are unaffected — separate channel. PRs #1 (base
 image 3.11.8 → 3.14.7) and #2 (actions group) are different ecosystems, are
 real decisions, and stay open.
+
+---
+
+## 11. Template sync — fence-aware source expansion (2026-08-23)
+
+Ported from `dash-documentation-boilerplate` 1.6.11 (`30075d0`): the
+fence-aware `_expand_source_directives` in `pages/markdown.py`, the
+every-page single-h1 / deduped-footer pin, and the fence unit test.
+
+**The upstream bug.** `_expand_source_directives` was a plain regex `sub`
+over the whole document, so a `.. source::` written *inside* a fenced block
+to TEACH the directive was expanded like a real one. The expansion injects
+its own ```` ```python ```` fence, which closes the already-open fence early
+— everything after it renders as markdown, and every `# comment` line in the
+inlined file becomes an `<h1>`. Five h1s on the template's tutorial page,
+machine lane only: markdown2dash parses fences properly, so the browser lane
+was always correct and nothing looked wrong to a human. The expander is now
+a line walker that tracks the open fence marker (``` and ~~~ both) and
+expands only at fence depth zero.
+
+**Prevention here, not a fix.** This fork has exactly one `.. source::` —
+`docs/reference_geo/geo.md:117`, inlining `lib/policy_store.py`, at top
+level. No page here teaches the directive inside a fence today. The port is
+for the day one does; the pin is what would catch it.
+
+**The sweep found no drift.** It ran over all 11 non-admin pages — every one
+serves exactly one `<h1>` to a generic client and a footer whose llms.txt
+links are distinct, with `/` carrying the root link once. The same sweep
+caught real content drift on two other forks (leaflet, muicharts), so the
+clean result here is a measurement, not an assumption.
+
+One adaptation: the template's pin skips `/admin/*` inline. This repo's
+`pages` fixture already drops it — the control board fails closed to
+anonymous renders and `tests/test_control_board.py` owns its assertions — so
+the guard would be dead code, and the docstring says where the exclusion
+actually lives.
+
+Also refreshed the prerender-lane test's floor wording: it still named 2.6.1
+as "the floor", which has been >=2.7.1 since Phase B.
+
+**602 passed / 1 skipped (flask), 599 passed / 4 skipped (fastapi)**,
+flake8 clean.

pages/markdown.py

@@ -90,9 +90,21 @@ def _expand_source_directives(markdown_content: str) -> str:
     `/<page>/llms.txt`. Replacing the directive with the real file content
     is what makes the LLM output self-contained for the "paste into a chat
     window" audience.
+
+    FENCE-AWARE, and it has to be: a directive INSIDE a fenced code block
+    is documentation showing the syntax, not a directive. Expanding it
+    injects a ```python fence inside the already-open fence, which CLOSES
+    it early — from there the inlined file renders as markdown, every
+    `# comment` line becomes an <h1>, and the machine lane of the page
+    serves broken structure. Found upstream 2026-08-23 by the single-h1
+    pin (template 1.6.11) on the boilerplate's docs/example and
+    docs/directives, which teach `.. source::` inside ```markdown fences;
+    no page here teaches it that way today, so this is prevention — but
+    the failure is silent on the browser lane (markdown2dash parses
+    fences properly), which is exactly why it went unnoticed there.
     """
-    def replace(match: re.Match) -> str:
-        file_path = match.group(1).strip()
+    def expansion(directive_line: str) -> str:
+        file_path = _SOURCE_DIRECTIVE.match(directive_line).group(1).strip()
         try:
             full = Path(file_path)
             content = full.read_text()
@@ -105,7 +117,19 @@ def replace(match: re.Match) -> str:
         except Exception as exc:
             return f'\n<!-- Error reading {file_path}: {exc} -->\n'
 
-    return _SOURCE_DIRECTIVE.sub(replace, markdown_content)
+    out: List[str] = []
+    fence = None  # the marker that opened the block we are inside, if any
+    for line in markdown_content.split('\n'):
+        head = line.lstrip()[:3]
+        if fence is None and head in ('```', '~~~'):
+            fence = head
+        elif fence is not None and head == fence:
+            fence = None
+        elif fence is None and _SOURCE_DIRECTIVE.match(line):
+            out.append(expansion(line))
+            continue
+        out.append(line)
+    return '\n'.join(out)
 
 
 def _build_llms_doc(name: str, description: str, expanded_markdown: str, path: str) -> str:

tests/test_pages.py

@@ -136,10 +136,84 @@ def test_prerender_rides_the_generic_lane_not_a_ua_gate(client):
         assert "hidden" not in div.group(0), (
             f"{path}: the prerender div carries `hidden` again — "
             "visibility-respecting consumers are back to reading "
-            "'Loading...'; the dimll floor is >=2.6.1 for exactly this"
+            "'Loading...'; the floor first moved (to 2.6.1) for exactly "
+            "this, and sits at >=2.7.1 now"
         )
         assert 'data-dimll-prerender="1">document.getElementById' in html, (
             f"{path}: the marked synchronous hide script is missing — "
             "JS browsers would flash the prose before React mounts"
         )
         assert "<main>" in html, f"{path}: prerender block carries no <main> prose"
+
+
+def test_prerender_single_h1_and_deduped_footer_llms_links(client, page_paths):
+    """What the >=2.7.1 floor buys, pinned from the app's side, EVERY page.
+
+    Below dimll 2.7.0 every page served TWO h1s to a generic client — the
+    injected prerender header plus the doc body's own markdown H1, a
+    duplicate-H1 page in every crawler's eyes (2026-08-22 SEO-audit
+    finding) — and the home footer printed its /llms.txt link twice (on
+    "/" the per-page link equals the root's; subpages legitimately carry
+    both, DISTINCT). The sweep also catches app-side H1 pollution: on the
+    template its first run found docs/example's machine lane serving FIVE
+    h1s because _expand_source_directives expanded a `.. source::` example
+    inside a ```markdown teaching fence (fixed fence-aware, 1.6.11 —
+    ported here, with tests below).
+
+    HTML comments are stripped before counting: templates/index.html
+    legitimately SAYS "<h1>" inside the comment explaining its noscript
+    block. /admin/* never reaches this sweep — the `pages` fixture drops
+    it, because the control board fails closed to anonymous renders and
+    tests/test_control_board.py owns its assertions.
+    """
+    for path in page_paths:
+        html = client.get(path).text  # default UA — the universal lane
+        stripped = re.sub(r"<!--.*?-->", "", html, flags=re.S)
+
+        h1s = re.findall(r"<h1[\s>]", stripped)
+        assert len(h1s) == 1, (
+            f"{path}: {len(h1s)} h1 elements in the generic-lane document — "
+            "either the pre-2.7.0 prerender-header duplicate or app-side "
+            "markdown leaking headings (the fence-expansion class)"
+        )
+
+        footer = re.search(r"<footer.*?</footer>", stripped, re.S)
+        assert footer, f"{path}: no prerender footer in the generic-lane document"
+        llms_links = re.findall(r'href="([^"]*llms\.txt)"', footer.group(0))
+        assert len(llms_links) == len(set(llms_links)), (
+            f"{path}: duplicate llms.txt links in the prerender footer "
+            f"({llms_links}) — 2.7.0 dedups the per-page link when it "
+            "equals the root"
+        )
+        if path == "/":
+            assert llms_links == ["/llms.txt"], (
+                f"home footer llms links {llms_links} — expected exactly the "
+                "root link once"
+            )
+
+
+def test_source_expansion_is_fence_aware(app):
+    """A `.. source::` inside a fenced block is documentation, not a directive.
+
+    The template's docs/example and docs/directives TEACH the directive
+    inside ```markdown fences. Expanding those injects a ```python fence
+    inside the already-open fence, which closes it early — from there the
+    inlined file renders as markdown on the machine lane and every
+    `# comment` line becomes an <h1> (the five-h1 finding, 2026-08-23).
+    No page here teaches it that way today, so this pin guards the day
+    one does. The app fixture is requested only so pages/markdown.py is
+    already imported with the repo root as CWD.
+    """
+    import sys
+
+    expand = sys.modules["pages.markdown"]._expand_source_directives
+
+    expanded = expand(".. source::requirements.txt")
+    assert "# File: requirements.txt" in expanded, "real directive not expanded"
+    assert "```" in expanded, "expansion lost its fence"
+
+    taught = "```markdown\n.. source::requirements.txt\n```"
+    assert expand(taught) == taught, "a fenced example was expanded"
+
+    tilde = "~~~\n.. source::requirements.txt\n~~~"
+    assert expand(tilde) == tilde, "a tilde-fenced example was expanded"