Copy buttons copied shell commands with their trailing `#` comments,
e.g. `wt hook pre-merge user: # Run all user hooks`. In zsh without
`interactivecomments`, which is the default, a pasted trailing comment
isn't a comment: the command runs as `wt hook pre-merge user: '#' Run
all user hooks`.
`withoutTrailingShellComments` in
`docs/src/plugins/worktrunk-terminal.mjs` applies the shell's rule, that
a `#` beginning an unquoted word starts a comment, to what shell copy
buttons copy: each per-line button in multi-command `console` blocks,
the command lines of single-command `console` blocks, and whole `bash`
and `sh` blocks. A line that is only a comment stays, as
`docs/CLAUDE.md` already specifies for console blocks. 56 of the site's
339 copy payloads change (47 per-line buttons and 9 `bash` blocks).
TOML, PowerShell and other payloads are unchanged, and a quoted `#`
survives.
Tests: unit tests for the scanner (quotes, escapes, `$#`, operators,
quotes spanning lines) and for a single-command `console` block with a
trailing comment, plus a built-site test that no `bash` or `sh` payload
carries a trailing comment, which fails on the build before this change.
> _This was written by Claude Code on behalf of max-sixty_
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_013U96NY8qKtZhavBSwnfCYq
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
On every shell code block the copy button sat 40px below the top of the
code: on the second line of multi-line blocks, and hanging below
one-line blocks such as `wt merge --no-ff` on /merge/. Shell blocks were
Expressive Code terminal frames, and the terminal plugin deleted their
title bar, but Expressive Code still offsets the copy button by that
bar's height.
## Changes
- `docs/astro.config.mjs` sets `defaultProps: { frame: 'code' }`, so no
block is a terminal frame and there is no title bar to remove. The
plugin's header-removal hook and its `props.frame = 'terminal'` go, and
so does the `wt-commands-only` class: mobile wrapping in `custom.css`
now keys on whether a block contains captured output
(`:has(.wt-output)`).
- Blocks with several commands had a whole-block copy button and
per-line buttons in the same corner, handed over on hover by opacity. A
hidden button still takes clicks, so clicking a line's button could copy
the whole block, and on touch screens one button covered another. Most
of these blocks are lists of alternatives, so they now get only per-line
buttons, and the hover rule is deleted.
- Those blocks wrap (Expressive Code's `wrap` prop) unless they carry
captured output, since a per-line button sits at the end of its line and
scrolled out of view on the long `jq` examples on /list/. A per-line
button is no taller than its line, so buttons on adjacent lines no
longer overlap.
- The two multi-command blocks that only work run in order, the FAQ's
stash recipe and the `Equivalent to:` block under `wt step diff`'s **How
it works** (in `src/cli/step.rs`), are now `bash` fences, the form
`docs/CLAUDE.md` prescribes for a copyable recipe, so they keep one copy
button for the whole recipe. Terminal `--help` renders `console` and
`bash` fences alike (it strips `$ `), and the help snapshots are
unchanged.
## Side effect
Expressive Code strips comment lines only from what terminal frames
copy. The eight `bash` and `powershell` blocks with comments on
/shell-integration/ now copy them, as console blocks already did. Pasted
into zsh without `interactivecomments`, each comment line prints
`command not found: #`; the commands still run.
## Tests
A browser test checks every copy button on every page, at 393px with
touch and at 1376px, for three things: it sits on the line it copies, it
is inside the visible code, and it doesn't overlap another button. These
checks fail against worktrunk.dev and against a build without the wrap
and the height cap. The built-site and plugin tests now expect per-line
payloads and no block payload on multi-command blocks, and a plugin test
pins that blocks carrying output never wrap.
> _This was written by Claude Code on behalf of max-sixty_
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_013U96NY8qKtZhavBSwnfCYq
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Command pages on the site append every subcommand's help, so headings
such as "Examples", "Options", and "Command reference" repeat down
`/step/` and `/config/`. The heading-id plugin numbered the repeats by
position (`/step/#examples-3`, `/step/#hooks-1`,
`/step/#command-reference-7`), so an anchor pointed somewhere else once
a same-named heading was added above it.
`docs/src/plugins/stable-heading-ids.mjs` now scopes ids below each
subcommand's H2 (a heading starting `wt `) by that section's id:
"Examples" under `wt step push` is `/step/#wt-step-push--examples`.
Page-level headings and the subcommand headings keep their ids, so the
table of contents and links like `/step/#wt-step-copy-ignored` are
unchanged. A slug never contains `--`, so a scoped id can't equal
another heading's slug — a "Cache" heading under `wt config state` stays
distinct from the `wt config state cache` section.
With the site handling it, the CLI help keeps unqualified headings.
#4000 renamed six `wt config` subcommand headings to "Approval
examples", "Alias examples", and so on to avoid the numbering; they're
back to "Examples", in `--help` as well.
Every anchor inside a subcommand section changes once:
`/step/#min-age-guard` is now `/step/#wt-step-prune--min-age-guard`. The
two internal links that pointed at such anchors — the FAQ's
copy-on-write link and `wt config approvals`' "Reading approval state" —
are updated, and `test:site` checks every internal fragment. External
links to the old anchors land at the top of the page.
The search-index plugin (`pagefind-command-references.mjs`) now imports
the subcommand-heading check from the heading-id plugin rather than
keeping its own copy.
> _This was written by Claude Code on behalf of max-sixty_
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01HUmx2Jd5mTK5TznqGDmLGp
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Extends the site’s semantic Bash colors to the homepage Worktrunk /
Plain git comparison in both responsive layouts. The build-only
transform keeps canonical Markdown, README, and skill mirrors plain
while preserving command text; WebKit verifies every colored token meets
WCAG contrast in both themes.
> _This was written by Codex on behalf of @max-sixty_
The Astro site kept the documentation content but lost some of the old
site's visual hierarchy: shell commands flattened into one color,
generated Command References had no semantic roles, dim terminal rows
were barely distinguishable, and file excerpts read like generic
untitled code. This restores those distinctions at their natural
rendering boundaries.
## What changed
- Add paired Worktrunk Shiki themes for source and shell syntax,
preserving the established warm palette with accessible light and dark
contrast.
- Mark generated Command Reference fences at their producer and render
Clap commands, headings, options, values, metadata, possible-value rows,
continued Usage signatures, and variadic metavariables semantically.
- Replace opacity-based terminal dimming with explicit accessible colors
while retaining ANSI hues.
- Present file excerpts as compact attached path tabs with a restrained
craft accent.
- Cover all 30 generated references, every public route at 320px and
393px in both themes, unrelated-fence false positives, command-only
copying, horizontal containment, and WCAG contrast in real WebKit
rendering.
## Mobile demos
The light and dark mobile homepage demos were already re-recorded and
published in `max-sixty/worktrunk-assets` at `4de7bde` by #3936. This
change verifies responsive source selection and viewport containment
against those current recordings, so another lossy re-record is
unnecessary.
## Testing
- `cargo run -- hook pre-merge --yes` — 4,722 passed, 1 skipped
- `cargo test --test integration test_docs_are_in_sync -- --nocapture`
- `npm --prefix docs test`
- `npm --prefix docs run build`
- `npm --prefix docs run test:site`
- `npm --prefix docs run check`
- independent systematic, adversarial, and from-scratch architecture
reviews
> _This was written by Codex on behalf of max-sixty_
## Summary
- re-record and publish both mobile homepage demos with restored ANSI
colors
- preserve exact ANSI roles in every snapshot-backed website terminal
while keeping Markdown portable
- wrap source and command snippets on mobile, contain fixed terminal
tables, and add real WebKit layout and contrast regressions
The corrected GIFs are already published in `max-sixty/worktrunk-assets`
at `4de7bde`.
## Testing
- `cargo run -- hook pre-merge --yes` (4,721 tests passed, 1 skipped)
- `npm --prefix docs run check`
- `npm --prefix docs test`
- `npm --prefix docs run build`
- `npm --prefix docs run test:site`
- independent frame review of both mobile GIF themes
- independent architecture, systematic, and adversarial reviews
Closes#3930Closes#3931
> _This was written by Codex on behalf of max-sixty._
The docs now build with Astro and Starlight instead of Zola. This
removes the Tera 2 migration blocker from #3827 while keeping the
published routes, anchors, generated references, metadata, and crawler
URLs stable. It replaces the approach closed in #3840.
## What changed
- Move the site into Starlight, with a custom Worktrunk homepage and a
shared copper, gold, paper, and ink design system.
- Keep generated docs as portable Markdown. The Rust sync pipeline no
longer needs Zola shortcodes, template escaping, ANSI-to-HTML
conversion, or reverse transforms for skill and README output.
- Preserve terminal semantics and command-only copying, add responsive
handling for short wide tables, retain stable heading IDs, and give
repeated command-reference headings useful search labels.
- Move docs CI and publishing to Node, Astro, and built-site contract
tests. The tests cover public routes, links, assets, metadata,
navigation, tables, terminal frames, and compatibility aliases.
- Record demo themes from isolated environments, add a mobile core demo,
and test the recording contract. The matching mobile assets are
published in `max-sixty/worktrunk-assets`.
Closes#3827.
## Verification
- `cargo run -- hook pre-merge --yes` (4,660 tests)
- `npm --prefix docs run check`
- `npm --prefix docs test` (9 tests)
- `npm --prefix docs run build` (16 pages)
- `npm --prefix docs run test:site` (12 tests)
- `pytest docs/demos/tests/test_recording.py` (4 tests)
> _This was written by Codex on behalf of max-sixty_
Maximilian Roos