ands or a however means break it up.docs/adr/ that record why a decision was made.mdn/content · github/docs · tldr-pages/tldr · any tool whose README is bad.
container CLI (Linux containers in lightweight VMs on Apple silicon, Apple's Docker Desktop alternative) with a new pages/osx/container.md. The writing was the small part; the real work was verification. Every one of the 8 examples comes from Apple's own command-reference.md for v1.0.0, not from memory, and that caught a real trap: the tool looks like Docker, but its Swift ArgumentParser CLI cannot group short flags, so the idiomatic docker -it must be written -i -t here. The page follows the tldr style guide: at most 8 examples, {{[-d|--detach]}} option placeholders so clients render short or long form, snake_case placeholders, and one user goal per example description. I claimed the issue with a comment before starting so nobody duplicates the work, rebuilt the branch on a freshly synced upstream main, and noted in the PR why the flags are ungrouped.
$ npx tldr-lint pages/osx/container.md (no errors) $ gh pr checks 23074 --repo tldr-pages/tldr labeler pass codespell pass license/cla pass Contributor License Agreement is signed.
osx since the tool is macOS-only.simply / just / easy anywhere in the page.tldr-lint their CI runs, before pushing.docs/. Rather than replace it, I switched the repo's Pages source to an Actions-based build and wrote a workflow that assembles both outputs into one artifact: the landing page keeps serving from the site root, and the new MkDocs Material site lands at /guide/. The content is genuinely three separate Diátaxis modes, not just three labels: a tutorial (scan your first folder), a how-to guide (read the treemap's colors, change the color scheme), and reference docs for ByteFormatter and TreemapLayout written straight from their source, including the real 10-category color table and the exact arc-angle formula.
$ mkdocs build --strict INFO - Cleaning site directory INFO - Building documentation to directory: .../site INFO - Documentation built in 0.16 seconds $ ls _site && ls _site/guide index.html logo.png privacy.html screenshot1.png ... guide/ how-to/ reference/ tutorial/ index.html search/
GlassCompat.swift's macOS 26 Liquid Glass calls compiled fine locally (only the macOS 26 SDK was installed) but failed on the macos-15 runner, because #available is a runtime check and does not stop the compiler from needing a symbol that only exists in a newer SDK. The fix was a compile-time #if compiler(>=6.2) guard wrapped around the existing #available check. Writing it as an ADR forced me to name the sharpest Consequence explicitly: any future Liquid Glass call site that copies a plain #available pattern from elsewhere in the codebase will silently reintroduce this exact bug, with no compiler warning to catch it.
# 0001. Guard Liquid Glass APIs with a compile-time check, not just #available ## Status Accepted, 2026-06-29. ## Decision Wrap every Liquid Glass call site with #if compiler(>=6.2) around the existing #available(macOS 26, *) check. ## Consequences + A future contributor copying a plain #available-only pattern elsewhere will reintroduce this bug silently. + The macos-15/macos-26 CI matrix is now load-bearing.
Vale.Spelling because the reference pages quote real API symbols (ByteFormatter, TreemapLayout), and set MinAlertLevel to error so clear-cut violations fail the build while advisory warnings still print but don't block. The styles are downloaded by vale sync, not committed, so CI stays reproducible from a clean checkout, which I verified by deleting the local styles dir and re-running the exact CI sequence before opening the change.
$ brew install vale $ vale sync $ vale guide docs/adr README.md # prove CI reproducibility from a clean checkout $ rm -rf .github/styles && vale sync && vale guide docs/adr README.md
.vale.ini configured with the Microsoft style; findings fixed. ✓/guide/ from a search has no path to the app at all. That is exactly the class of bug this exercise exists to catch: the writer's context (I know where the download is) silently baked into the page. The fix is PR #11, two links: a "Not installed yet?" pointer on the guide home and an install link in the tutorial's prerequisites.