Repository navigation
Verify doc outputs and tighten every docs page - #297
Merged
Merged
Conversation
The suite only proved that each block runs. It now rewrites every single-line form with a ; => comment into a check and fails on a mismatch, with the same baseline and ratchet used for blocks that cannot run.
npm run check:docs fails on a description outside 50 to 160 characters, a language page without a difficulty, ;; => or ;; prints, a blockquote, a Phel release older than config.toml outside upgrading.md, a page that opens with a heading, and an H1 in the body. CI runs it. The pages that broke a rule are fixed.
zola check only follows @/ links, and this site writes absolute ones.
A practice list in the front matter renders one tip card under the page.
Chemaclass
marked this pull request as ready for review
October 28, 2026 12:22
Chemaclass
commented
Oct 28, 2026
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
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.
The docs hold hundreds of
; => valuecomments inside Phel code blocks, and the snippet suite only checked that each block runs. A wrong value could sit there for years. The suite now rewrites everyform ; => value(or a; => valueline right below the form) into a check and fails on a mismatch, using the same baseline and ratchet it already has for blocks that cannot run. Mismatch reports start on a new line so output fromprintcannot hide a wrong result; an end-to-end regression covers this case. Lines whose expected text is not data (..., "instance",#') are skipped and listed under--verbose.First value caught:
(assoc p :x 10)on the data structures page said(point 10 2); Phel prints(user.point 10 2).Also in this PR
npm run check:docs(scripts/check-docs.js) checks every docs page, and CI runs it: a description of 50 to 160 characters, adifficultyon every language page,; =>and; printswith one semicolon, the callout component instead of a blockquote, no Phel release older thanconfig.tomloutside upgrading.md, a lead paragraph before the first H2, and no H1 in the body. The 21 pages that broke a rule are fixed. The error reference intro is now a plain paragraph, since that page skips templating and cannot use the callout.CI runs
npm run check:linksafterzola build.zola checkonly follows@/links, and this site writes absolute ones.Aliases for old URLs that 404 today:
/documentation/guides/phel-for-php-developers,/documentation/language/arithmetic,/documentation/language/truth-and-boolean-operations,/documentation/numbers-and-arithmetic,/documentation/reference/one-liners,/documentation/debug,/documentation/debug/php-tools,/documentation/debug/phel-helpers,/documentation/commands,/documentation/tutorials,/documentation/tooling/authoring-libraries,/documentation/reference/in-the-wild./documentation/guides/aialready redirects throughstatic/.htaccess.Each core language page links to its practice module:
practice = [...]in the front matter renders one tip card at the end of the page.Sidebar links no longer replay the slide-in animation on navigation. Sections open and close immediately, and link transitions only animate colors so collapsed links leave view and the tab order immediately.
Checked
composer test:snippets: 554 snippets pass, 869 documented values checked, 0 mismatches, empty baseline.vendor/bin/phpunit(135 tests) andcomposer phpstan.npm run check:docs: 0 problems.zola build,zola check --skip-external-linksandnpm run check:links: 9816 links, 0 broken.Sidebar navigation and all six section toggles checked with mouse and keyboard at 1440px and 390px, in light and dark themes. No horizontal overflow.
CSS formatting passes. CSS lint has 50 existing errors in the two changed files, with no new errors.