docs: drop synthetic "A minimal example" / "Refinement:" prefixes from headings#262
Merged
docs: drop synthetic "A minimal example" / "Refinement:" prefixes from headings#262
Conversation
…m headings 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).
4 tasks
adamziel
added a commit
that referenced
this pull request
May 3, 2026
Stack on top of #262 (the heading-prefix change). Replaces 1,128 lines of Python tooling with 762 lines of PHP. The toolkit now documents itself using only its own runtime — no Python in CI, no second language to context-switch into when iterating on the docs. Replaces: bin/_docs_components.py (dead-code dicts, 200 lines) bin/_load_catalog.py (frontmatter + section + snippet parser, 370 lines) bin/build-reference.py (docs/reference/<slug>.html generator, 220 lines) bin/run-snippets.py (snippet runner + expected-output checker, 230 lines) bin/serve-docs.py (CORS-enabled local preview server, 50 lines) With: bin/build-reference.php (parser + renderer, 480 lines — also the catalog-loading library, since run-snippets.php requires it) bin/run-snippets.php (runner + expected-output writer, 250 lines) bin/serve-docs.php (php -S router with CORS headers, 50 lines) Behavioural parity: - 87/87 snippets match captured stdout (same expected-output blocks as before; the new parser produces byte-identical normalization and fence handling). - docs/reference/*.html renders byte-equivalent output: same HTML structure, same snippet/fallback/expected-output triples, same pitfall extraction, same see-also rendering. - --update writes captured stdout back into the same expected-output fence in the README via the same slug → directory map. Format change: see_also frontmatter switched from repeated keys (`see_also: a | A | r` × 3) to a proper YAML list: see_also: - a | A | reason - b | B | reason This is standard YAML — readable by any frontmatter-aware tool, and correctly typed as a sequence in GitHub's README renderer. The Python parser never accepted the YAML-list form; the new PHP parser only accepts that form. Workflows simplified: - snippet-tests.yml drops the `actions/setup-python` step. - docs.yml drops `python3 bin/build-reference.py` for `php bin/build-reference.php`. Per the prompt in docs-changes.md ("Change all the markdown-handling python tooling to use PHP. Reuse components from this repo."): the new PHP code uses standard library facilities (preg_*, proc_open) — none of the toolkit components needed any new feature, so no stack-base PR was required.
adamziel
added a commit
that referenced
this pull request
May 3, 2026
Stack on top of #262 (the heading-prefix change). Replaces 1,128 lines of Python tooling with 762 lines of PHP. The toolkit now documents itself using only its own runtime — no Python in CI, no second language to context-switch into when iterating on the docs. Replaces: bin/_docs_components.py (dead-code dicts, 200 lines) bin/_load_catalog.py (frontmatter + section + snippet parser, 370 lines) bin/build-reference.py (docs/reference/<slug>.html generator, 220 lines) bin/run-snippets.py (snippet runner + expected-output checker, 230 lines) bin/serve-docs.py (CORS-enabled local preview server, 50 lines) With: bin/build-reference.php (parser + renderer, 480 lines — also the catalog-loading library, since run-snippets.php requires it) bin/run-snippets.php (runner + expected-output writer, 250 lines) bin/serve-docs.php (php -S router with CORS headers, 50 lines) Behavioural parity: - 87/87 snippets match captured stdout (same expected-output blocks as before; the new parser produces byte-identical normalization and fence handling). - docs/reference/*.html renders byte-equivalent output: same HTML structure, same snippet/fallback/expected-output triples, same pitfall extraction, same see-also rendering. - --update writes captured stdout back into the same expected-output fence in the README via the same slug → directory map. Format change: see_also frontmatter switched from repeated keys (`see_also: a | A | r` × 3) to a proper YAML list: see_also: - a | A | reason - b | B | reason This is standard YAML — readable by any frontmatter-aware tool, and correctly typed as a sequence in GitHub's README renderer. The Python parser never accepted the YAML-list form; the new PHP parser only accepts that form. Workflows simplified: - snippet-tests.yml drops the `actions/setup-python` step. - docs.yml drops `python3 bin/build-reference.py` for `php bin/build-reference.php`. Per the prompt in docs-changes.md ("Change all the markdown-handling python tooling to use PHP. Reuse components from this repo."): the new PHP code uses standard library facilities (preg_*, proc_open) — none of the toolkit components needed any new feature, so no stack-base PR was required.
adamziel
added a commit
that referenced
this pull request
May 3, 2026
Stack on top of #262 (the heading-prefix change). Replaces 1,128 lines of Python tooling with 762 lines of PHP. The toolkit now documents itself using only its own runtime — no Python in CI, no second language to context-switch into when iterating on the docs. Replaces: bin/_docs_components.py (dead-code dicts, 200 lines) bin/_load_catalog.py (frontmatter + section + snippet parser, 370 lines) bin/build-reference.py (docs/reference/<slug>.html generator, 220 lines) bin/run-snippets.py (snippet runner + expected-output checker, 230 lines) bin/serve-docs.py (CORS-enabled local preview server, 50 lines) With: bin/build-reference.php (parser + renderer, 480 lines — also the catalog-loading library, since run-snippets.php requires it) bin/run-snippets.php (runner + expected-output writer, 250 lines) bin/serve-docs.php (php -S router with CORS headers, 50 lines) Behavioural parity: - 87/87 snippets match captured stdout (same expected-output blocks as before; the new parser produces byte-identical normalization and fence handling). - docs/reference/*.html renders byte-equivalent output: same HTML structure, same snippet/fallback/expected-output triples, same pitfall extraction, same see-also rendering. - --update writes captured stdout back into the same expected-output fence in the README via the same slug → directory map. Format change: see_also frontmatter switched from repeated keys (`see_also: a | A | r` × 3) to a proper YAML list: see_also: - a | A | reason - b | B | reason This is standard YAML — readable by any frontmatter-aware tool, and correctly typed as a sequence in GitHub's README renderer. The Python parser never accepted the YAML-list form; the new PHP parser only accepts that form. Workflows simplified: - snippet-tests.yml drops the `actions/setup-python` step. - docs.yml drops `python3 bin/build-reference.py` for `php bin/build-reference.php`. Per the prompt in docs-changes.md ("Change all the markdown-handling python tooling to use PHP. Reuse components from this repo."): the new PHP code uses standard library facilities (preg_*, proc_open) — none of the toolkit components needed any new feature, so no stack-base PR was required.
adamziel
added a commit
that referenced
this pull request
May 3, 2026
Stack on top of #262 (the heading-prefix change). Replaces 1,128 lines of Python tooling with 762 lines of PHP. The toolkit now documents itself using only its own runtime — no Python in CI, no second language to context-switch into when iterating on the docs. Replaces: bin/_docs_components.py (dead-code dicts, 200 lines) bin/_load_catalog.py (frontmatter + section + snippet parser, 370 lines) bin/build-reference.py (docs/reference/<slug>.html generator, 220 lines) bin/run-snippets.py (snippet runner + expected-output checker, 230 lines) bin/serve-docs.py (CORS-enabled local preview server, 50 lines) With: bin/build-reference.php (parser + renderer, 480 lines — also the catalog-loading library, since run-snippets.php requires it) bin/run-snippets.php (runner + expected-output writer, 250 lines) bin/serve-docs.php (php -S router with CORS headers, 50 lines) Behavioural parity: - 87/87 snippets match captured stdout (same expected-output blocks as before; the new parser produces byte-identical normalization and fence handling). - docs/reference/*.html renders byte-equivalent output: same HTML structure, same snippet/fallback/expected-output triples, same pitfall extraction, same see-also rendering. - --update writes captured stdout back into the same expected-output fence in the README via the same slug → directory map. Format change: see_also frontmatter switched from repeated keys (`see_also: a | A | r` × 3) to a proper YAML list: see_also: - a | A | reason - b | B | reason This is standard YAML — readable by any frontmatter-aware tool, and correctly typed as a sequence in GitHub's README renderer. The Python parser never accepted the YAML-list form; the new PHP parser only accepts that form. Workflows simplified: - snippet-tests.yml drops the `actions/setup-python` step. - docs.yml drops `python3 bin/build-reference.py` for `php bin/build-reference.php`. Per the prompt in docs-changes.md ("Change all the markdown-handling python tooling to use PHP. Reuse components from this repo."): the new PHP code uses standard library facilities (preg_*, proc_open) — none of the toolkit components needed any new feature, so no stack-base PR was required.
adamziel
added a commit
that referenced
this pull request
May 3, 2026
Stack on top of #262 (the heading-prefix change). Replaces 1,128 lines of Python tooling with 762 lines of PHP. The toolkit now documents itself using only its own runtime — no Python in CI, no second language to context-switch into when iterating on the docs. Replaces: bin/_docs_components.py (dead-code dicts, 200 lines) bin/_load_catalog.py (frontmatter + section + snippet parser, 370 lines) bin/build-reference.py (docs/reference/<slug>.html generator, 220 lines) bin/run-snippets.py (snippet runner + expected-output checker, 230 lines) bin/serve-docs.py (CORS-enabled local preview server, 50 lines) With: bin/build-reference.php (parser + renderer, 480 lines — also the catalog-loading library, since run-snippets.php requires it) bin/run-snippets.php (runner + expected-output writer, 250 lines) bin/serve-docs.php (php -S router with CORS headers, 50 lines) Behavioural parity: - 87/87 snippets match captured stdout (same expected-output blocks as before; the new parser produces byte-identical normalization and fence handling). - docs/reference/*.html renders byte-equivalent output: same HTML structure, same snippet/fallback/expected-output triples, same pitfall extraction, same see-also rendering. - --update writes captured stdout back into the same expected-output fence in the README via the same slug → directory map. Format change: see_also frontmatter switched from repeated keys (`see_also: a | A | r` × 3) to a proper YAML list: see_also: - a | A | reason - b | B | reason This is standard YAML — readable by any frontmatter-aware tool, and correctly typed as a sequence in GitHub's README renderer. The Python parser never accepted the YAML-list form; the new PHP parser only accepts that form. Workflows simplified: - snippet-tests.yml drops the `actions/setup-python` step. - docs.yml drops `python3 bin/build-reference.py` for `php bin/build-reference.php`. Per the prompt in docs-changes.md ("Change all the markdown-handling python tooling to use PHP. Reuse components from this repo."): the new PHP code uses standard library facilities (preg_*, proc_open) — none of the toolkit components needed any new feature, so no stack-base PR was required.
adamziel
added a commit
that referenced
this pull request
May 3, 2026
Stack on top of #262 (the heading-prefix change). Replaces 1,128 lines of Python tooling with 762 lines of PHP. The toolkit now documents itself using only its own runtime — no Python in CI, no second language to context-switch into when iterating on the docs. Replaces: bin/_docs_components.py (dead-code dicts, 200 lines) bin/_load_catalog.py (frontmatter + section + snippet parser, 370 lines) bin/build-reference.py (docs/reference/<slug>.html generator, 220 lines) bin/run-snippets.py (snippet runner + expected-output checker, 230 lines) bin/serve-docs.py (CORS-enabled local preview server, 50 lines) With: bin/build-reference.php (parser + renderer, 480 lines — also the catalog-loading library, since run-snippets.php requires it) bin/run-snippets.php (runner + expected-output writer, 250 lines) bin/serve-docs.php (php -S router with CORS headers, 50 lines) Behavioural parity: - 87/87 snippets match captured stdout (same expected-output blocks as before; the new parser produces byte-identical normalization and fence handling). - docs/reference/*.html renders byte-equivalent output: same HTML structure, same snippet/fallback/expected-output triples, same pitfall extraction, same see-also rendering. - --update writes captured stdout back into the same expected-output fence in the README via the same slug → directory map. Format change: see_also frontmatter switched from repeated keys (`see_also: a | A | r` × 3) to a proper YAML list: see_also: - a | A | reason - b | B | reason This is standard YAML — readable by any frontmatter-aware tool, and correctly typed as a sequence in GitHub's README renderer. The Python parser never accepted the YAML-list form; the new PHP parser only accepts that form. Workflows simplified: - snippet-tests.yml drops the `actions/setup-python` step. - docs.yml drops `python3 bin/build-reference.py` for `php bin/build-reference.php`. Per the prompt in docs-changes.md ("Change all the markdown-handling python tooling to use PHP. Reuse components from this repo."): the new PHP code uses standard library facilities (preg_*, proc_open) — none of the toolkit components needed any new feature, so no stack-base PR was required.
adamziel
added a commit
that referenced
this pull request
May 3, 2026
Stack on top of #262 (the heading-prefix change). Replaces 1,128 lines of Python tooling with 762 lines of PHP. The toolkit now documents itself using only its own runtime — no Python in CI, no second language to context-switch into when iterating on the docs. Replaces: bin/_docs_components.py (dead-code dicts, 200 lines) bin/_load_catalog.py (frontmatter + section + snippet parser, 370 lines) bin/build-reference.py (docs/reference/<slug>.html generator, 220 lines) bin/run-snippets.py (snippet runner + expected-output checker, 230 lines) bin/serve-docs.py (CORS-enabled local preview server, 50 lines) With: bin/build-reference.php (parser + renderer, 480 lines — also the catalog-loading library, since run-snippets.php requires it) bin/run-snippets.php (runner + expected-output writer, 250 lines) bin/serve-docs.php (php -S router with CORS headers, 50 lines) Behavioural parity: - 87/87 snippets match captured stdout (same expected-output blocks as before; the new parser produces byte-identical normalization and fence handling). - docs/reference/*.html renders byte-equivalent output: same HTML structure, same snippet/fallback/expected-output triples, same pitfall extraction, same see-also rendering. - --update writes captured stdout back into the same expected-output fence in the README via the same slug → directory map. Format change: see_also frontmatter switched from repeated keys (`see_also: a | A | r` × 3) to a proper YAML list: see_also: - a | A | reason - b | B | reason This is standard YAML — readable by any frontmatter-aware tool, and correctly typed as a sequence in GitHub's README renderer. The Python parser never accepted the YAML-list form; the new PHP parser only accepts that form. Workflows simplified: - snippet-tests.yml drops the `actions/setup-python` step. - docs.yml drops `python3 bin/build-reference.py` for `php bin/build-reference.php`. Per the prompt in docs-changes.md ("Change all the markdown-handling python tooling to use PHP. Reuse components from this repo."): the new PHP code uses standard library facilities (preg_*, proc_open) — none of the toolkit components needed any new feature, so no stack-base PR was required.
adamziel
added a commit
that referenced
this pull request
May 3, 2026
Stack on top of #262 (the heading-prefix change). Replaces 1,128 lines of Python tooling with 762 lines of PHP. The toolkit now documents itself using only its own runtime — no Python in CI, no second language to context-switch into when iterating on the docs. Replaces: bin/_docs_components.py (dead-code dicts, 200 lines) bin/_load_catalog.py (frontmatter + section + snippet parser, 370 lines) bin/build-reference.py (docs/reference/<slug>.html generator, 220 lines) bin/run-snippets.py (snippet runner + expected-output checker, 230 lines) bin/serve-docs.py (CORS-enabled local preview server, 50 lines) With: bin/build-reference.php (parser + renderer, 480 lines — also the catalog-loading library, since run-snippets.php requires it) bin/run-snippets.php (runner + expected-output writer, 250 lines) bin/serve-docs.php (php -S router with CORS headers, 50 lines) Behavioural parity: - 87/87 snippets match captured stdout (same expected-output blocks as before; the new parser produces byte-identical normalization and fence handling). - docs/reference/*.html renders byte-equivalent output: same HTML structure, same snippet/fallback/expected-output triples, same pitfall extraction, same see-also rendering. - --update writes captured stdout back into the same expected-output fence in the README via the same slug → directory map. Format change: see_also frontmatter switched from repeated keys (`see_also: a | A | r` × 3) to a proper YAML list: see_also: - a | A | reason - b | B | reason This is standard YAML — readable by any frontmatter-aware tool, and correctly typed as a sequence in GitHub's README renderer. The Python parser never accepted the YAML-list form; the new PHP parser only accepts that form. Workflows simplified: - snippet-tests.yml drops the `actions/setup-python` step. - docs.yml drops `python3 bin/build-reference.py` for `php bin/build-reference.php`. Per the prompt in docs-changes.md ("Change all the markdown-handling python tooling to use PHP. Reuse components from this repo."): the new PHP code uses standard library facilities (preg_*, proc_open) — none of the toolkit components needed any new feature, so no stack-base PR was required.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Section headings on each reference page now match the README's H2 lines verbatim. The renderer was rewriting:
…regardless of what the README actually said.
Test plan
🤖 Generated with Claude Code