Documentation Verification in CI
The lykn test --docs step is the most unusual part of the pipeline. Most projects don’t test their documentation. Lykn does.
What It Catches
Compiler changes that break examples. A surface form’s output changes — perhaps bind now emits a slightly different variable declaration, or func adjusts its whitespace. Every “Compiles to:” block in every Markdown file that shows the old output is now wrong. Without automated testing, those examples stay wrong until a reader notices, files an issue, and waits for a fix. With lykn test --docs, the CI build fails immediately.
Anti-patterns that stop being anti-patterns. Documentation often includes ```lykn,compile-fail or ```lisp,compile-fail blocks showing code that should fail — demonstrating what the compiler rejects. When a new feature accidentally makes one of these examples valid, the documentation test catches it. The anti-pattern is no longer an anti-pattern, and the documentation needs updating.
Output drift. The compiled JavaScript for a given Lykn input may change subtly between compiler versions — additional semicolons, reordered declarations, different whitespace. The Markdown test catches the drift before it becomes a discrepancy between what the documentation shows and what the compiler actually produces.
What It Doesn’t Catch
Prose that contradicts the code. If a paragraph says “this produces an array” but the code example clearly produces an object, no automated test will catch it. That’s a human review. The tool verifies code, not claims about code.
Runtime behavior. A bare selected Lykn block is compile-checked only. If the code compiles but does something unexpected at runtime, the test passes. Use ```lykn,run or ```lisp,run for examples where runtime correctness matters.
The Self-Referential Quality
A healthy Lykn project can test its documentation in CI. This book uses the same mechanism during the 0.6.0 refresh: selected fences are compiled or run, failures are fixed or routed, and the final edition will not rely on hand-waved examples. The reader should see documentation whose code claims have been mechanically checked, which is a higher bar than most technical writing clears, and a lower bar than most technical writing should.