The `wt list` JSON-output section (and every command-recipe block on the
docs site) rendered badly: the blank lines between recipes showed as
stray bare `$` prompts, and long `jq` pipelines overflowed the block's
right edge — scrolling out of view behind macOS's hidden overlay
scrollbar, so the tail of a command was simply invisible.
The recipe content in `src/cli/mod.rs` is clean Markdown; the defects
were entirely in the docs rendering layer, so the fix lives there and
leaves the auto-generated pages and the CLI source untouched.
- `docs/templates/shortcodes/terminal.html` — empty `|||` segments now
emit a real blank line instead of a `$ ` prompt, and command-only blocks
(no fixed-width output body) get a `terminal--commands` class.
- `docs/sass/custom.scss` — `.terminal--commands code { white-space:
pre-wrap }` wraps long pipelines at spaces, falling back to horizontal
scroll only for a single unbreakable token. Fixed-width tables and ASCII
output are untagged and keep their existing no-wrap + horizontal-scroll
behavior.
Verified against a local Zola build on `/list/` and `/tips-patterns/`:
command blocks wrap with 0px overflow, show no stray prompts, and keep
their group spacing; the three `wt list` tables are unaffected. No
`white-space` override exists in the narrow-width media queries, so
wrapping holds on mobile.
> _This was written by Claude Code on behalf of max_
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The table CSS used `.content > table`, which skipped tables inside
`<details>` and any other wrapper — they fell back to browser defaults
(no borders, 1px padding, mid-aligned cells). Most visibly, the
"Interface differences" table on `/extending/` looked unstyled.
Switched to a descendant selector for both the main rule and the print
rule so nested tables pick up the same styling.
Co-authored-by: Claude <noreply@anthropic.com>
The approval prompt examples on the hook and FAQ pages were plain code
blocks with no styling, while the CLI renders them with colored symbols
and syntax-highlighted commands. The `wt merge` example on the LLM
commits page had the same issue.
Adds yellow ▲, dim ○, cyan ❯/◎, gutter bars on command lines, and bash
syntax highlighting (blue commands, green strings, cyan
flags/operators). Also replaces echo placeholders with real commands and
fixes the "3 commands" header that previously only showed 1 command.
Changes: `post_process_for_html()` in help.rs for auto-generated
hook.md, direct edits for manually-maintained faq.md and llm-commits.md,
`.y` and `.b` CSS classes.
> _This was written by Claude Code on behalf of @max-sixty_
---------
Co-authored-by: Claude <noreply@anthropic.com>
The badge was inside Zola's `<a class="zola-anchor">` wrapper because it
was on the heading line in markdown. Now generated on a separate line
after the heading, with CSS `:has()` selectors collapsing the badge's
`<p>` wrapper to flow inline with the heading. No JS needed.
Two generation paths updated:
- `post_process_for_html()` — new `move_experimental_from_headings()`
splits heading-line badges to separate lines (terminal help unchanged)
- `format_subcommand_section()` — emits badge span after heading, not on
it
Also: `vertical-align: 0.15em` for better vertical centering (was
`middle`, which aligned too low).
Includes the heading-position fix from #1734 (squash-merged earlier).
> _This was written by Claude Code on behalf of maximilian_
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Move experimental badges from the start of description paragraphs to
after the heading text in web docs.
Uses empty `<span>` elements with CSS `::after` for badge text, so the
span doesn't affect Zola's heading slug generation or page TOC entries.
This avoids the need for `{#slug}` anchor overrides and keeps sidebar
TOC entries clean (no "experimental" suffix).
Before: `## wt step relocate` / `EXPERIMENTAL Move worktrees to expected
paths.`
After: `## wt step relocate EXPERIMENTAL` / `Move worktrees to expected
paths.`
> _This was written by Claude Code on behalf of @max-sixty_
---------
Co-authored-by: Claude <noreply@anthropic.com>
Replaces plain `[experimental]` text in web docs with styled pill badges
— small uppercase labels with a subtle border that read as metadata
rather than emphasis.
Canonicalizes all experimental markers to `[experimental]` (was a mix of
`[experimental]`, `(experimental)`, `(Experimental)`). One marker format
in cli.rs, one `.replace()` in the post-processing.
Also renames `colorize_ci_status_for_html` → `post_process_for_html` (it
handles badges and URLs too), adds a module docstring documenting the
full `--help-page` pipeline, and fixes a latent double-application of
the post-processor on subdoc content.
> _This was written by Claude Code on behalf of @max-sixty_
---------
Co-authored-by: Claude <noreply@anthropic.com>
## Summary
- Migrate from static CSS syntax highlighting to Zola's giallo engine
with custom `worktrunk-light.json` theme
- Replace hardcoded `syntax-light.css` / `syntax-dark.css` with
theme-based class generation
- Design a warm "sunlit workshop" palette: amber commands, gold strings,
chartreuse quoted strings, rusty constants
- Add CSS sibling selector to differentiate quoted from bare strings
(giallo tokenizes both as `z-string`)
## Test plan
- [ ] Verify syntax colors on `/switch/` (bash: commands, flags,
strings, quoted strings)
- [ ] Verify TOML blocks on `/config/` (section headers, keys, values)
- [ ] Verify dark mode is unaffected (quoted string CSS rule scoped to
`prefers-color-scheme: light`)
- [ ] Check all tests pass (`cargo test`)
> _This was written by Claude Code on behalf of @max-sixty_
---------
Co-authored-by: Claude <noreply@anthropic.com>
* refactor(docs): simplify CSS with shared placeholders and design tokens
- Extract duplicate H1/H2 underline styles to %heading-underline placeholder
- Add border-radius scale CSS variables (--wt-radius-sm/md/lg/pill)
- Consolidate duplicate .button shadow definitions
- Remove redundant TOC hover state and gentle-bounce animation
- Standardize all border-radius values to use design tokens
Net: -23 lines, more consistent design system.
Co-Authored-By: Claude <noreply@anthropic.com>
* fix(docs): increase TOC child item padding for better hover targets
Child items had only 0.1rem vertical padding (cramped), now 0.35rem.
Also removed redundant 0.15rem bottom padding on the li element since
anchor padding now provides sufficient spacing.
Co-Authored-By: Claude <noreply@anthropic.com>
* fix(docs): add missing H4 margin definitions
H4 lacked margin-top/bottom, now matches heading hierarchy pattern.
Co-Authored-By: Claude <noreply@anthropic.com>
* fix(docs): standardize heading margin ratios to 4:1
- h2: 1.5rem -> 1.6rem top margin (now 4:1 with 0.4rem bottom)
- h3: 1.25rem -> 1.2rem top margin (now 4:1 with 0.3rem bottom)
All headings now use consistent 4:1 top:bottom margin ratio.
Co-Authored-By: Claude <noreply@anthropic.com>
* fix(docs): use CSS variable for asymmetric border-radius
Images and code blocks with left accent borders now use
var(--wt-radius-md) instead of hardcoded 0.5rem.
Co-Authored-By: Claude <noreply@anthropic.com>
* fix(docs): increase TOC H1 item font-size for better hierarchy
H1 section markers in TOC now use 0.8rem font-size (same as parent
command items) instead of inheriting 0.75rem from child items.
Creates clearer visual hierarchy between H1 and H2 entries.
Co-Authored-By: Claude <noreply@anthropic.com>
* fix(docs): reduce TOC child item vertical padding for better density
0.35rem was too tall, making it hard to see all items on one page.
0.2rem provides a good balance between hover target size and density.
Co-Authored-By: Claude <noreply@anthropic.com>
* fix(docs): make TOC links fill parent elements for consistent cursor
Move padding from <li> to <a> elements so links fill the entire
clickable area. This eliminates dead zones where pointer cursor
showed but nothing was clickable.
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
* docs: add Quick Start section to front page
Shows the basic workflow with clear directory paths at each stage:
- Create worktree with wt switch --create
- Check status with wt list
- Two merge paths: PR workflow (push + gh pr create + wt remove)
and local merge (wt merge)
- Parallel agents example with -x flag
Co-Authored-By: Claude <noreply@anthropic.com>
* docs: improve Quick Start with realistic examples and snapshot sync
- Add snapshot-based output sync for quickstart examples (switch, list, merge)
- Make examples more realistic: 53 lines of auth module changes instead of 9
- Show uncommitted changes in wt list demo (WIP state, not already committed)
- Add wt step commit to PR workflow since changes are now uncommitted
- Remove redundant git push from PR workflow (gh pr create auto-pushes)
- Suppress worktree-path hint in quickstart tests for cleaner output
- Add transform_zola_to_github() for converting HTML terminal markers to plain code blocks
Co-Authored-By: Claude <noreply@anthropic.com>
* Simplify code block formatting in README and tests
Convert bash code blocks to console format with command prompts and output
in a single block. Update regex pattern to optionally strip redundant bash
preamble when converting AUTO-GENERATED-HTML terminal markers.
* docs: remove redundant bash blocks before terminal examples
The terminal shortcodes already include the command with $ prefix,
so separate bash blocks showing just the command were redundant.
Also fix broken anchor link in config.md.
Co-Authored-By: Claude <noreply@anthropic.com>
* feat(docs): make terminal prompt non-copyable via CSS
Use CSS ::before pseudo-element to generate the $ prompt, making it
structurally non-copyable. This works with both manual text selection
and copy buttons.
Changes:
- Add .cmd::before { content: "$ "; } to generate prompt via CSS
- Remove explicit <span class="prompt">$</span> from HTML output
- Extract command from snapshot YAML header instead of parsing HTML
- Update expand_command_placeholders for command pages (list.md, etc.)
Co-Authored-By: Claude <noreply@anthropic.com>
* fix(docs): show commit step in quick start merge example
The merge example now shows staged changes being committed as part of
the wt merge workflow, reflecting a realistic user experience where
code is staged but not yet committed before merging.
Co-Authored-By: Claude <noreply@anthropic.com>
* style: fix cargo fmt formatting
Co-Authored-By: Claude <noreply@anthropic.com>
* fix(tests): use cross-platform mock LLM for quickstart_merge test
The quickstart_merge test was using a shell script for the mock LLM
which doesn't work on Windows. Now uses the mock-stub system which
creates a cross-platform mock binary.
Co-Authored-By: Claude <noreply@anthropic.com>
* fix(test): use to_slash_lossy for Windows path compatibility
Windows paths with backslashes trigger shell metacharacter handling,
which wraps the command in `sh -c`. Bash can't parse Windows paths
like `C:\Users\...`. Converting to forward slashes with
to_slash_lossy() makes the path bash-compatible.
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
* docs(config): add H1 major sections with TOC support (#857)
* docs(config): add H1 major sections with TOC support
Add H1 headings for major sections (User Configuration, Project
Configuration, Shell Integration, Environment Variables) to improve
navigation and visual hierarchy.
Theme changes:
- Include H1s in sidebar TOC with divider lines
- Fix H1 link color (was orange due to missing zola-anchor rule)
- Style H1 headings consistently with H2 (underline, size)
Co-Authored-By: Claude <noreply@anthropic.com>
* docs(config): improve TOC structure and auto-generate Subcommands header
- Auto-insert "# Subcommands" in help.rs before subdoc expansions
- Add "# Other" section containing Environment Variables and Command reference
- Rename "Commands" to "Command config" for clarity
- Fix TOC styling: align H1/H2 text, reduce vertical spacing, use sentence case
- Template: show H2s nested under H1s at same indent as standalone H2s
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: address codex review feedback
- Add default guard for h.children in TOC template
- Remove ineffective :first-of-type selector
Co-Authored-By: Claude <noreply@anthropic.com>
* docs: use sentence case for Environment variables
Co-Authored-By: Claude <noreply@anthropic.com>
* test: update snapshots for config section header changes
Co-Authored-By: Claude <noreply@anthropic.com>
* test: update help_config_create snapshot
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
* fix(docs): prevent h1 styling from breaking hero layout
The H1 major sections commit added `width: fit-content` and underline
styling to all h1 elements. This broke the hero because:
- fit-content shrinks the element, breaking text-align: center
- The underline appeared on the hero title
Fix by overriding these in .heading-text (used for page titles/hero):
- width: auto to restore centering
- > a::after { display: none } to hide underline
Co-Authored-By: Claude <noreply@anthropic.com>
* fix(docs): align H1 TOC entries with H2s
Remove left border and custom padding from H1 entries in the sidebar
TOC. H1s are now distinguished only by bolder weight and extra top
margin, creating a cleaner visual hierarchy.
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
* docs(config): add H1 major sections with TOC support
Add H1 headings for major sections (User Configuration, Project
Configuration, Shell Integration, Environment Variables) to improve
navigation and visual hierarchy.
Theme changes:
- Include H1s in sidebar TOC with divider lines
- Fix H1 link color (was orange due to missing zola-anchor rule)
- Style H1 headings consistently with H2 (underline, size)
Co-Authored-By: Claude <noreply@anthropic.com>
* docs(config): improve TOC structure and auto-generate Subcommands header
- Auto-insert "# Subcommands" in help.rs before subdoc expansions
- Add "# Other" section containing Environment Variables and Command reference
- Rename "Commands" to "Command config" for clarity
- Fix TOC styling: align H1/H2 text, reduce vertical spacing, use sentence case
- Template: show H2s nested under H1s at same indent as standalone H2s
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: address codex review feedback
- Add default guard for h.children in TOC template
- Remove ineffective :first-of-type selector
Co-Authored-By: Claude <noreply@anthropic.com>
* docs: use sentence case for Environment variables
Co-Authored-By: Claude <noreply@anthropic.com>
* test: update snapshots for config section header changes
Co-Authored-By: Claude <noreply@anthropic.com>
* test: update help_config_create snapshot
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
Move overflow-x from figure.demo to the picture element so the
figcaption stays in place while the image scrolls horizontally.
Co-authored-by: Claude <noreply@anthropic.com>
Simplify link styling with permanent underline and animated accent on
hover. Update inline code with new color variable and remove padding
from code inside links. Add CSS custom property for inline code text
color in both light and dark themes.
Wrap code blocks in a container div so the copy button stays fixed at
the top-right corner when scrolling horizontally. Previously the button
would scroll with the code content.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
Hide demo images until they finish loading to prevent broken-image icon
flash. Add JavaScript to detect load completion and visibility toggle via
CSS class. Update demo figure styles to support dynamic visibility and
maintain aspect ratio during scroll.
The 1Password browser extension rewrites code blocks with `language-*`
classes, replacing Zola's syntect-generated spans with its own Prism tokens.
This breaks all syntax highlighting colors.
Fix: Add `data-1p-ignore` attribute to code blocks via MutationObserver,
which tells 1Password to skip processing these elements.
Also fix CSS to let syntax highlighting colors apply by removing hardcoded
color from code blocks and using `color: inherit` for `.content pre code`.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
Change table width from 100% to fit-content with max-width constraint
to allow tables to display at their natural width while preventing
overflow beyond the container.
Update documentation examples to use shorter branch names and refactor table
styling to properly handle horizontal scrolling within the content area. Tables
now use display: block with overflow-x: auto instead of display: table with
max-content width, preventing layout overflow while maintaining border-radius
appearance.
Replace hardcoded shadow values with CSS custom properties for consistency
across light and dark modes. Update image dimensions in documentation.
Consolidate code block and terminal styles using SCSS mixins. Improve
table styling with proper border-collapse and overflow handling. Add print
styles for better document output. Expand demo placeholder parser to
support optional dimension attributes.
Replace generic `all` transitions with explicit property lists to improve
performance and maintainability. Specifies only the properties that actually
change on interaction (color, background, box-shadow, text-decoration).
- Add `insert_anchor_links = "heading"` to Zola markdown config for automatic heading anchors
- Style anchor links with hover effects: h2 underlines intensify, h3/h4 shift to accent color
- Add `scroll-margin-top` to content area to account for sticky header when scrolling to anchors
- Wrap homepage and page title headings with anchor links for deep linking
- Add new test fixtures: `repo_with_remote_and_feature`, `repo_with_alternate_primary`, `repo_with_multi_commit_feature`, and `add_feature()` shorthand
- Consolidate help tests from individual functions to parameterized rstest
- Update directives and merge/push tests to use new fixture helpers
- Update snapshot tests with corrected commit messages from new fixture usage
Refactor search container to use :focus-within for expanded state and
view-transition-name to freeze the search box during page navigation.
This prevents layout shifts caused by input shrinking when focus is lost
during the view transition. Update search.js to only clear suggestions
on modifier-click (new tab/window) to avoid jarring shrink during normal
navigation.
- Add Contributing section to README with star, feedback, feature request,
and share links
- Add social icon buttons to docs footer (GitHub, Crates.io, X, Reddit,
LinkedIn) replacing redundant text links
- Move FAQ "How can I contribute?" section to bottom of page
- Update share links to point to worktrunk.dev instead of GitHub
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
Custom "warm workbench" theme now self-contained without Juice inheritance. Eliminates theme extension complexity and provides complete control over documentation site design.
Key changes:
- Removed docs/themes/juice submodule and all Juice template inheritance
- Rewrote base.html as standalone template with full HTML structure
- Migrated all Juice CSS variables and utilities into custom.scss
- Updated config.toml to remove theme reference and rename juice_* config keys
- Consolidated template structure: page.html and index.html now extend base.html directly
- Removed lychee exclusion for Juice theme README (no longer applicable)
- Moved normalize.css from theme to docs/static for direct control
The theme is now fully self-hosted with no external dependencies, making it easier to maintain and extend.
h1 and .heading-text elements previously used padding-left: 0
while other padding directions remained unset. Changed to use the
padding shorthand with value 0 to explicitly define all padding
sides and improve consistency with the spacing refactor.
Demo images now use `<figure class="demo">` instead of plain markdown to enable horizontal scrolling on small screens while maintaining readability.
Updates both manual demo markup in select.md and why-worktrunk.md, plus the code generation for demo placeholders in expand_demo_placeholders().
Adds .content figure.demo styling with min-width: 800px to shrink until readable, then scroll. Also reduces code block hover transition from 100ms to 50ms for snappier feedback.
Add visual distinction to images with left accent border and refined
shadow. Convert demo images to semantic figure elements with captions.
Simplify figure styling to inherit image rules consistently across all
content.
Use HTML5 `<figure>` and `<figcaption>` instead of markdown image syntax
for better semantic markup and accessibility. Add descriptive alt text and
caption explaining the demo workflow (create, work, merge).
Also add corresponding SCSS styles for figure and figcaption elements with
centered alignment and muted text color for captions.
Changed max-width from none to 100% so images scale down to fit
their container while maintaining aspect ratio. Added box-sizing
to ensure borders are included in width calculations for more
predictable layout behavior.
- Add horizontal scrolling and consistent styling to images in documentation
- Update remove command help text to clarify argument resolution and shortcuts
Remove overflow-x: hidden from html to allow table scrolling. Add display: block and overflow-x: auto to tables with touch-friendly scrolling. Add white-space: nowrap to cells to keep content on single lines during horizontal scroll.
Add overflow-x: hidden to html element to eliminate unwanted page-level
horizontal scrolling on mobile. Internal content with overflow-x: auto
can still scroll horizontally as intended. This complements the existing
scrollbar-gutter: stable rule for layout stability.
Details now live in base.html next to the JS fix.
CLAUDE.md just references it. Fixed outdated comments
that incorrectly claimed lvh was stable on Firefox iOS.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The `--vh-full` CSS variable and its JavaScript polyfill are no longer needed.
Modern browsers including iOS Safari 17+ support `lvh` (large viewport height)
natively and correctly. Using `100lvh` directly eliminates the polyfill overhead
and simplifies the codebase while maintaining stable viewport behavior on iOS.
Remove -webkit-fill-available workarounds that caused layout thrashing.
The polyfill now captures viewport height once at load and only updates
on actual device rotation (orientationchange), eliminating the jank from
continuous resize/scroll event handling. CSS fallback to 100lvh remains
stable on modern browsers.
Replace svh/lvh with -webkit-fill-available on iOS WebKit browsers, which
provides stable viewport height against browser chrome animation without
relying on broken minimumViewportInset/maximumViewportInset APIs.
Enhanced the viewport height polyfill to track the minimum of innerHeight,
clientHeight, and visualViewport.height across resize, orientationchange, and
visualViewport events. This captures the smallest available space to approximate
the "small viewport" used by Safari when browser chrome is fully visible.
Applied -webkit-fill-available to html, body, .hero, and .mobile-menu elements
within the iOS WebKit @supports block. Used SCSS string interpolation to bypass
calc() parsing and preserve the full expression for browser evaluation.
Firefox iOS incorrectly implements svh as dvh, causing scroll jank
when browser chrome appears/disappears. lvh (large viewport height)
should be stable.
Also simplify JS and remove --safe-area-top workaround that didn't help.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
If hero doesn't jank with height: auto, confirms viewport-based
sizing is the cause on Firefox iOS.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Replace direct env(safe-area-inset-top) calls with a JS-locked CSS variable
(--safe-area-top) to prevent scroll jank on Firefox iOS and Chrome iOS when
browser chrome appears/disappears during scrolling.
The env() value fluctuates during toolbar animation, causing layout shifts.
By reading the computed safe area inset once on page load and caching it in
a CSS variable, we provide a stable value throughout the viewport lifecycle.
Updates all usages in header, hero section, mobile menu, and media queries
to use the locked variable with env() as fallback.
Maximilian Roos