From c0c0ceca3eff38196f07e84c24b51dc96f51266d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adam=20Zieli=C5=84ski?= Date: Sun, 3 May 2026 23:21:55 +0200 Subject: [PATCH] docs: drop synthetic 'A minimal example' / 'Refinement:' prefixes from headings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Section headings on each reference page now match the README's H2 lines verbatim. The renderer used to lowercase the first letter of every non-first snippet section and prefix it with `Refinement: `, and rewrite the first snippet section to `A minimal example`, regardless of what the README actually said. Result before: ## A minimal example ← was "Add loading=lazy to every image" ## Refinement: rewrite relative links… ← was "Rewrite relative links…" ## Refinement: strip every script… Result after: ## Add loading="lazy" to every image ## Rewrite relative links to absolute URLs ## Strip every script and inline event handler The README author writes the heading they mean. The renderer doesn't relabel it. Anchor IDs change accordingly (slugified from the new heading), so any external link to e.g. /reference/html.html#a-minimal-example becomes /reference/html.html#add-loadinglazy-to-every-image. The first-section-with-a-snippet is still tracked internally (minimal_emitted) for future logic, but it no longer triggers a heading rewrite. Snippets still match captured stdout (87/87). --- bin/build-reference.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/bin/build-reference.py b/bin/build-reference.py index b8401993c..b79c59d54 100644 --- a/bin/build-reference.py +++ b/bin/build-reference.py @@ -188,12 +188,13 @@ def render_component(components, c): snippet = section['snippet'] rest, found = split_pitfalls(body_html) pitfalls.extend(found) + # Use the section's own heading verbatim — no synthetic prefixes. + # The first section in a component that ships a snippet doubles as + # the "minimal example" by convention; readers can tell it from + # later sections by its position, not by an editorial label. h2 = heading if not minimal_emitted and snippet: - h2 = 'A minimal example' minimal_emitted = True - elif snippet: - h2 = f'Refinement: {heading[0].lower() + heading[1:]}' if heading else heading out.append(f'

{h(h2)}

\n\n') if rest: out.append(rest + '\n\n')