Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

Syntect highlighting for template expression blocks (#1792)

Maximilian Roosbd9b9fe29352
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index e45717b03..fadbfef28 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -226,11 +226,12 @@ All shell commands use `$ ` prefix in `` ```console `` blocks. `convert_dollar_c
| Detected pattern | Web output | Highlighting |
|------------------|------------|--------------|
-| Any `$ ` commands, no `{{ }}` | `cmd` parameter with `\|\|\|` delimiter | Full Syntect |
-| `{{ }}` in command | `{% terminal() %}` with `<span class="cmd">` body | Accent color only |
+| `$ ` commands | `cmd` parameter with `\|\|\|` delimiter | Full Syntect |
| No `$ ` | `console` → `bash` conversion | Syntect (no `$ ` prompt) |
-The `cmd` parameter supports multiple commands joined by `|||`. The template splits, highlights each through Syntect individually, and wraps commands in `<span class="cmd">` (CSS `::before` adds `$ `). Comment lines (`#`) are highlighted but not wrapped (no prompt).
+All `$ ` commands go through the `cmd` parameter path for consistent Syntect highlighting. Multiple commands are joined by `|||`; the template splits and highlights each individually. Commands are wrapped in `<span class="cmd">` (CSS `::before` adds `$ `). Comment lines (`#`) are highlighted but not wrapped (no prompt).
+
+**Placeholders in cmd values:** Tera (Zola's template engine) would interpret `{{ }}` in the `cmd` parameter as template expressions, and `"` would close the parameter string. Since Tera has no backslash-escape mechanism for string literals, these characters are replaced with text placeholders (`__WT_OPEN2__`, `__WT_CLOSE2__`, `__WT_QUOT__`) in the Rust conversion function. The terminal shortcode template replaces them back before Syntect highlighting. The sync test also strips them when generating skill reference files.
Hand-written docs can use either `console` fences with `$ ` (auto-converted by the sync test) or shortcodes directly.
@@ -249,7 +250,7 @@ The `--help-page` generator in `src/main.rs` applies post-processing to transfor
| CLI Source | Web Output |
|------------|------------|
-| `` ```console `` with `$ ` | `{% terminal() %}` with `<span class="cmd">` |
+| `` ```console `` with `$ ` | `terminal` shortcode with `cmd` parameter |
| `` ```console `` (no `$ `) | `` ```bash `` |
| `` `●` green `` | `<span style='color:#0a0'>●</span> green` |
| `` `●` blue `` | `<span style='color:#00a'>●</span> blue` |
diff --git a/docs/content/config.md b/docs/content/config.md
index bfcacf1c8..e07eaf69b 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -409,7 +409,7 @@ Note the single underscore after `WORKTRUNK` and double underscores between nest
Override the LLM command in CI to use a mock:
-{{ terminal(cmd="WORKTRUNK_COMMIT__GENERATION__COMMAND=&quot;echo 'test: automated commit'&quot; wt merge") }}
+{{ terminal(cmd="WORKTRUNK_COMMIT__GENERATION__COMMAND=__WT_QUOT__echo 'test: automated commit'__WT_QUOT__ wt merge") }}
### Other environment variables
@@ -527,7 +527,7 @@ Set the default branch manually:
{{ terminal(cmd="wt config state default-branch set main") }}
Set a marker for current branch:
-{{ terminal(cmd="wt config state marker set &quot;🚧 WIP&quot;") }}
+{{ terminal(cmd="wt config state marker set __WT_QUOT__🚧 WIP__WT_QUOT__") }}
Clear all CI status cache:
{{ terminal(cmd="wt config state ci-status clear --all") }}
@@ -704,7 +704,7 @@ bugfix 🤖!↑⇡ ~/code/myproject.bugfix
Stored in git config as `worktrunk.state.<branch>.marker`. Set directly with:
-{{ terminal(cmd="git config worktrunk.state.feature.marker '{&quot;marker&quot;:&quot;🚧&quot;,&quot;set_at&quot;:0}'") }}
+{{ terminal(cmd="git config worktrunk.state.feature.marker '{__WT_QUOT__marker__WT_QUOT__:__WT_QUOT__🚧__WT_QUOT__,__WT_QUOT__set_at__WT_QUOT__:0}'") }}
Without a subcommand, runs `get` for the current branch. For `--branch`, use `get --branch=NAME`.
@@ -777,7 +777,7 @@ Query the command log:
{{ terminal(cmd="tail -5 .git/wt/logs/commands.jsonl | jq .") }}
View a specific hook log:
-{{ terminal(cmd="cat &quot;$(git rev-parse --git-dir)/wt/logs/feature-project-post-start-build.log&quot;") }}
+{{ terminal(cmd="cat __WT_QUOT__$(git rev-parse --git-dir)/wt/logs/feature-project-post-start-build.log__WT_QUOT__") }}
Clear all logs:
{{ terminal(cmd="wt config state logs clear") }}
diff --git a/docs/content/hook.md b/docs/content/hook.md
index bfce919d1..bf199a0fd 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -199,7 +199,7 @@ if ctx['branch'].startswith('feature/') and 'backend' in ctx['repo']:
`wt hook <type>` runs hooks on demand — useful for testing during development, running in CI pipelines, or re-running after a failure.
-{{ terminal(cmd="wt hook pre-merge # Run all pre-merge hooks|||wt hook pre-merge test # Run hooks named &quot;test&quot; from both sources|||wt hook pre-merge user: # Run all user hooks|||wt hook pre-merge project: # Run all project hooks|||wt hook pre-merge user:test # Run only user's &quot;test&quot; hook|||wt hook pre-merge project:test # Run only project's &quot;test&quot; hook|||wt hook pre-merge --yes # Skip approval prompts (for CI)|||wt hook pre-start --var branch=feature/test # Override template variable") }}
+{{ terminal(cmd="wt hook pre-merge # Run all pre-merge hooks|||wt hook pre-merge test # Run hooks named __WT_QUOT__test__WT_QUOT__ from both sources|||wt hook pre-merge user: # Run all user hooks|||wt hook pre-merge project: # Run all project hooks|||wt hook pre-merge user:test # Run only user's __WT_QUOT__test__WT_QUOT__ hook|||wt hook pre-merge project:test # Run only project's __WT_QUOT__test__WT_QUOT__ hook|||wt hook pre-merge --yes # Skip approval prompts (for CI)|||wt hook pre-start --var branch=feature/test # Override template variable") }}
The `user:` and `project:` prefixes filter by source. Use `user:` or `project:` alone to run all hooks from that source, or `user:name` / `project:name` to run a specific hook.
diff --git a/docs/content/list.md b/docs/content/list.md
index be1e82c47..01febe9bb 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -136,7 +136,7 @@ These appear across all columns while the table is loading:
Query structured data with `--format=json`:
-{{ terminal(cmd="# Current worktree path (for scripts)|||wt list --format=json | jq -r '.[] | select(.is_current) | .path'||||||# Branches with uncommitted changes|||wt list --format=json | jq '.[] | select(.working_tree.modified)'||||||# Worktrees with merge conflicts|||wt list --format=json | jq '.[] | select(.operation_state == &quot;conflicts&quot;)'||||||# Branches ahead of main (needs merging)|||wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'||||||# Integrated branches (safe to remove)|||wt list --format=json | jq '.[] | select(.main_state == &quot;integrated&quot; or .main_state == &quot;empty&quot;) | .branch'||||||# Branches without worktrees|||wt list --format=json --branches | jq '.[] | select(.kind == &quot;branch&quot;) | .branch'||||||# Worktrees ahead of remote (needs pushing)|||wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'||||||# Stale CI (local changes not reflected in CI)|||wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'") }}
+{{ terminal(cmd="# Current worktree path (for scripts)|||wt list --format=json | jq -r '.[] | select(.is_current) | .path'||||||# Branches with uncommitted changes|||wt list --format=json | jq '.[] | select(.working_tree.modified)'||||||# Worktrees with merge conflicts|||wt list --format=json | jq '.[] | select(.operation_state == __WT_QUOT__conflicts__WT_QUOT__)'||||||# Branches ahead of main (needs merging)|||wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'||||||# Integrated branches (safe to remove)|||wt list --format=json | jq '.[] | select(.main_state == __WT_QUOT__integrated__WT_QUOT__ or .main_state == __WT_QUOT__empty__WT_QUOT__) | .branch'||||||# Branches without worktrees|||wt list --format=json --branches | jq '.[] | select(.kind == __WT_QUOT__branch__WT_QUOT__) | .branch'||||||# Worktrees ahead of remote (needs pushing)|||wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'||||||# Stale CI (local changes not reflected in CI)|||wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'") }}
**Fields:**
diff --git a/docs/content/step.md b/docs/content/step.md
index 10db87718..efec8fdff 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -258,7 +258,7 @@ The diff is pipeable to tools like `delta`:
Equivalent to:
-{{ terminal(cmd="cp &quot;$(git rev-parse --git-dir)/index&quot; /tmp/idx|||GIT_INDEX_FILE=/tmp/idx git add --intent-to-add .|||GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state default-branch))") }}
+{{ terminal(cmd="cp __WT_QUOT__$(git rev-parse --git-dir)/index__WT_QUOT__ /tmp/idx|||GIT_INDEX_FILE=/tmp/idx git add --intent-to-add .|||GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state default-branch))") }}
`git diff` ignores untracked files. `git add --intent-to-add .` registers them in the index without staging their content, making them visible to `git diff`. This runs against a copy of the real index so the original is never modified.
@@ -438,35 +438,29 @@ All [hook template variables and filters](@/hook.md#template-variables) are avai
Get the port for the current branch:
-{% terminal() %}
-<span class="cmd">wt step eval '{{ branch | hash_port }}'</span>
+{% terminal(cmd="wt step eval '__WT_OPEN2__ branch | hash_port __WT_CLOSE2__'") %}
16066
{% end %}
Use in shell substitution:
-{% terminal() %}
-<span class="cmd">curl http://localhost:$(wt step eval '{{ branch | hash_port }}')/health</span>
-{% end %}
+{{ terminal(cmd="curl http://localhost:$(wt step eval '__WT_OPEN2__ branch | hash_port __WT_CLOSE2__')/health") }}
Combine multiple values:
-{% terminal() %}
-<span class="cmd">wt step eval '{{ branch | hash_port }},{{ ("supabase-api-" ~ branch) | hash_port }}'</span>
+{% terminal(cmd="wt step eval '__WT_OPEN2__ branch | hash_port __WT_CLOSE2__,__WT_OPEN2__ (__WT_QUOT__supabase-api-__WT_QUOT__ ~ branch) | hash_port __WT_CLOSE2__'") %}
16066,16739
{% end %}
Use conditionals and filters:
-{% terminal() %}
-<span class="cmd">wt step eval '{{ branch | sanitize_db }}'</span>
+{% terminal(cmd="wt step eval '__WT_OPEN2__ branch | sanitize_db __WT_CLOSE2__'") %}
feature_auth_oauth2_a1b
{% end %}
Show available template variables:
-{% terminal() %}
-<span class="cmd">wt step eval --dry-run '{{ branch }}'</span>
+{% terminal(cmd="wt step eval --dry-run '__WT_OPEN2__ branch __WT_CLOSE2__'") %}
branch=feature/auth-oauth2
worktree_path=/home/user/projects/myapp-feature-auth-oauth2
...
@@ -530,13 +524,11 @@ Run npm install in all worktrees:
Use branch name in command:
-{% terminal() %}
-<span class="cmd">wt step for-each -- "echo Branch: {{ branch }}"</span>
-{% end %}
+{{ terminal(cmd="wt step for-each -- __WT_QUOT__echo Branch: __WT_OPEN2__ branch __WT_CLOSE2____WT_QUOT__") }}
Pull updates in worktrees with upstreams (skips others):
-{{ terminal(cmd="git fetch --prune && wt step for-each -- '[ &quot;$(git rev-parse @{u} 2>/dev/null)&quot; ] || exit 0; git pull --autostash'") }}
+{{ terminal(cmd="git fetch --prune && wt step for-each -- '[ __WT_QUOT__$(git rev-parse @{u} 2>/dev/null)__WT_QUOT__ ] || exit 0; git pull --autostash'") }}
Note: This command is experimental and may change in future versions.
diff --git a/docs/templates/shortcodes/terminal.html b/docs/templates/shortcodes/terminal.html
index c70593ffb..8f072b49e 100644
--- a/docs/templates/shortcodes/terminal.html
+++ b/docs/templates/shortcodes/terminal.html
@@ -8,6 +8,7 @@
{% endif %}
<pre class="terminal"><code>
{%- for cmd_line in cmd_lines -%}
+{%- set cmd_line = cmd_line | replace(from="__WT_OPEN2__", to="{{") | replace(from="__WT_CLOSE2__", to="}}") | replace(from="__WT_QUOT__", to='"') -%}
{%- set md = fence ~ "bash
" ~ cmd_line ~ "
" ~ fence -%}
diff --git a/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.md
index 4255b4737..34d83adc5 100644
--- a/skills/worktrunk/reference/claude-code.md
+++ b/skills/worktrunk/reference/claude-code.md
@@ -7,8 +7,10 @@ The worktrunk Claude Code plugin provides two features:
## Installation
-<span class="cmd">claude plugin marketplace add max-sixty/worktrunk</span>
-<span class="cmd">claude plugin install worktrunk@worktrunk</span>
+```bash
+$ claude plugin marketplace add max-sixty/worktrunk
+$ claude plugin install worktrunk@worktrunk
+```
## Configuration skill
@@ -25,7 +27,8 @@ Claude Code is designed to load the skill automatically when it detects worktrun
The plugin tracks Claude sessions with status markers in `wt list`:
-<span class="cmd">wt list</span>
+```bash
+$ wt list
<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Remote⇅</b> <b>Path</b> <b>Commit</b> <b>Age</b> <b>Message</b>
@ main <span class=d>^</span><span class=d>⇡</span> <span class=g>⇡1</span> . <span class=d>33323bc1</span> <span class=d>1d</span> <span class=d>Initial commit</span>
+ feature-api <span class=d>↑</span> 🤖 <span class=g>↑1</span> ../repo.feature-api <span class=d>70343f03</span> <span class=d>1d</span> <span class=d>Add REST API endpoints</span>
@@ -33,6 +36,7 @@ The plugin tracks Claude sessions with status markers in `wt list`:
+ wip-docs <span class=c>?</span> <span class=d>–</span> ../repo.wip-docs <span class=d>33323bc1</span> <span class=d>1d</span> <span class=d>Initial commit</span>
<span class=d>○</span> <span class=d>Showing 4 worktrees, 2 with changes, 2 ahead</span>
+```
- 🤖 — Claude is working
- 💬 — Claude is waiting for input
@@ -41,9 +45,11 @@ The plugin tracks Claude sessions with status markers in `wt list`:
Set status markers manually for any workflow:
-<span class="cmd">wt config state marker set "🚧" # Current branch</span>
-<span class="cmd">wt config state marker set "✅" --branch feature # Specific branch</span>
-<span class="cmd">git config worktrunk.state.feature.marker '{"marker":"💬","set_at":0}' # Direct</span>
+```bash
+$ wt config state marker set "🚧" # Current branch
+$ wt config state marker set "✅" --branch feature # Specific branch
+$ git config worktrunk.state.feature.marker '{"marker":"💬","set_at":0}' # Direct
+```
## Statusline
diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.md
index 5e5ab03aa..8d1599364 100644
--- a/skills/worktrunk/reference/config.md
+++ b/skills/worktrunk/reference/config.md
@@ -411,7 +411,7 @@ Note the single underscore after `WORKTRUNK` and double underscores between nest
Override the LLM command in CI to use a mock:
```bash
-$ WORKTRUNK_COMMIT__GENERATION__COMMAND=&quot;echo 'test: automated commit'&quot; wt merge
+$ WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge
```
### Other environment variables
@@ -533,7 +533,7 @@ $ wt config state default-branch set main
Set a marker for current branch:
```bash
-$ wt config state marker set &quot;🚧 WIP&quot;
+$ wt config state marker set "🚧 WIP"
```
Clear all CI status cache:
@@ -714,7 +714,7 @@ bugfix 🤖!↑⇡ ~/code/myproject.bugfix
Stored in git config as `worktrunk.state.<branch>.marker`. Set directly with:
```bash
-$ git config worktrunk.state.feature.marker '{&quot;marker&quot;:&quot;🚧&quot;,&quot;set_at&quot;:0}'
+$ git config worktrunk.state.feature.marker '{"marker":"🚧","set_at":0}'
```
Without a subcommand, runs `get` for the current branch. For `--branch`, use `get --branch=NAME`.
@@ -791,7 +791,7 @@ $ tail -5 .git/wt/logs/commands.jsonl | jq .
View a specific hook log:
```bash
-$ cat &quot;$(git rev-parse --git-dir)/wt/logs/feature-project-post-start-build.log&quot;
+$ cat "$(git rev-parse --git-dir)/wt/logs/feature-project-post-start-build.log"
```
Clear all logs:
diff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.md
index 4f4f97760..b2a6c94ea 100644
--- a/skills/worktrunk/reference/faq.md
+++ b/skills/worktrunk/reference/faq.md
@@ -10,20 +10,24 @@ Branch switching uses one directory: uncommitted changes from one agent get mixe
Git's built-in worktree commands work but require manual lifecycle management:
+```bash
# Plain git worktree workflow
-<span class="cmd">git worktree add -b feature-branch ../myapp-feature main</span>
-<span class="cmd">cd ../myapp-feature</span>
+$ git worktree add -b feature-branch ../myapp-feature main
+$ cd ../myapp-feature
# ...work, commit, push...
-<span class="cmd">cd ../myapp</span>
-<span class="cmd">git merge feature-branch</span>
-<span class="cmd">git worktree remove ../myapp-feature</span>
-<span class="cmd">git branch -d feature-branch</span>
+$ cd ../myapp
+$ git merge feature-branch
+$ git worktree remove ../myapp-feature
+$ git branch -d feature-branch
+```
Worktrunk automates the full lifecycle:
-<span class="cmd">wt switch --create feature-branch # Creates worktree, runs setup hooks</span>
+```bash
+$ wt switch --create feature-branch # Creates worktree, runs setup hooks
# ...work...
-<span class="cmd">wt merge # Merges into default branch, cleans up</span>
+$ wt merge # Merges into default branch, cleans up
+```
No cd back to main — `wt merge` runs from the feature worktree and merges into the target, like GitHub's merge button.
@@ -179,11 +183,13 @@ All hook executions and LLM commands are recorded in `.git/wt/logs/commands.json
View the log with `wt config state logs get`, or query directly:
+```bash
# Recent commands
-<span class="cmd">tail -5 .git/wt/logs/commands.jsonl | jq .</span>
+$ tail -5 .git/wt/logs/commands.jsonl | jq .
# Failed commands
-<span class="cmd">jq 'select(.exit != 0 and .exit != null)' .git/wt/logs/commands.jsonl</span>
+$ jq 'select(.exit != 0 and .exit != null)' .git/wt/logs/commands.jsonl
+```
Clear with `wt config state logs clear`.
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index 3ba77b1ed..3fe1c6542 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -189,7 +189,14 @@ if ctx['branch'].startswith('feature/') and 'backend' in ctx['repo']:
`wt hook <type>` runs hooks on demand — useful for testing during development, running in CI pipelines, or re-running after a failure.
```bash
-$ wt hook pre-merge # Run all pre-merge hooks|||wt hook pre-merge test # Run hooks named &quot;test&quot; from both sources|||wt hook pre-merge user: # Run all user hooks|||wt hook pre-merge project: # Run all project hooks|||wt hook pre-merge user:test # Run only user's &quot;test&quot; hook|||wt hook pre-merge project:test # Run only project's &quot;test&quot; hook|||wt hook pre-merge --yes # Skip approval prompts (for CI)|||wt hook pre-start --var branch=feature/test # Override template variable
+$ wt hook pre-merge # Run all pre-merge hooks
+$ wt hook pre-merge test # Run hooks named "test" from both sources
+$ wt hook pre-merge user: # Run all user hooks
+$ wt hook pre-merge project: # Run all project hooks
+$ wt hook pre-merge user:test # Run only user's "test" hook
+$ wt hook pre-merge project:test # Run only project's "test" hook
+$ wt hook pre-merge --yes # Skip approval prompts (for CI)
+$ wt hook pre-start --var branch=feature/test # Override template variable
```
The `user:` and `project:` prefixes filter by source. Use `user:` or `project:` alone to run all hooks from that source, or `user:name` / `project:name` to run a specific hook.
diff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.md
index b3c791853..49577a5b4 100644
--- a/skills/worktrunk/reference/list.md
+++ b/skills/worktrunk/reference/list.md
@@ -129,7 +129,29 @@ These appear across all columns while the table is loading:
Query structured data with `--format=json`:
```bash
-$ # Current worktree path (for scripts)|||wt list --format=json | jq -r '.[] | select(.is_current) | .path'||||||# Branches with uncommitted changes|||wt list --format=json | jq '.[] | select(.working_tree.modified)'||||||# Worktrees with merge conflicts|||wt list --format=json | jq '.[] | select(.operation_state == &quot;conflicts&quot;)'||||||# Branches ahead of main (needs merging)|||wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'||||||# Integrated branches (safe to remove)|||wt list --format=json | jq '.[] | select(.main_state == &quot;integrated&quot; or .main_state == &quot;empty&quot;) | .branch'||||||# Branches without worktrees|||wt list --format=json --branches | jq '.[] | select(.kind == &quot;branch&quot;) | .branch'||||||# Worktrees ahead of remote (needs pushing)|||wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'||||||# Stale CI (local changes not reflected in CI)|||wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
+# Current worktree path (for scripts)
+$ wt list --format=json | jq -r '.[] | select(.is_current) | .path'
+
+# Branches with uncommitted changes
+$ wt list --format=json | jq '.[] | select(.working_tree.modified)'
+
+# Worktrees with merge conflicts
+$ wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'
+
+# Branches ahead of main (needs merging)
+$ wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'
+
+# Integrated branches (safe to remove)
+$ wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty") | .branch'
+
+# Branches without worktrees
+$ wt list --format=json --branches | jq '.[] | select(.kind == "branch") | .branch'
+
+# Worktrees ahead of remote (needs pushing)
+$ wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'
+
+# Stale CI (local changes not reflected in CI)
+$ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
```
**Fields:**
diff --git a/skills/worktrunk/reference/llm-commits.md b/skills/worktrunk/reference/llm-commits.md
index 1ceb1966d..9be94acbd 100644
--- a/skills/worktrunk/reference/llm-commits.md
+++ b/skills/worktrunk/reference/llm-commits.md
@@ -49,10 +49,13 @@ These examples assume a feature worktree with changes to commit.
Squashes all changes (uncommitted + existing commits) into one commit with an LLM-generated message, then merges to the default branch:
+```bash
+$ wt merge
<span class=c>◎</span> <span class=c>Squashing 3 commits into a single commit <span style='color:var(--bright-black,#555)'>(5 files, <span class=g>+48</span></span></span><span style='color:var(--bright-black,#555)'>)</span>...
<span class=c>◎</span> <span class=c>Generating squash commit message...</span>
<span style='background:var(--bright-white,#fff)'> </span> <b>feat(auth): Implement JWT authentication system</b>
<span style='background:var(--bright-white,#fff)'> </span> ...
+```
### wt step commit
diff --git a/skills/worktrunk/reference/remove.md b/skills/worktrunk/reference/remove.md
index a493df9c2..1e3748edd 100644
--- a/skills/worktrunk/reference/remove.md
+++ b/skills/worktrunk/reference/remove.md
@@ -13,7 +13,8 @@ $ wt remove
Remove specific worktrees / branches:
```bash
-$ wt remove feature-branch|||wt remove old-feature another-branch
+$ wt remove feature-branch
+$ wt remove old-feature another-branch
```
Keep the branch:
@@ -54,7 +55,9 @@ Worktrunk has two force flags for different situations:
| `--force-delete` (`-D`) | Branch | Branch has unmerged commits |
```bash
-$ wt remove feature --force # Remove worktree with untracked files|||wt remove feature -D # Delete unmerged branch|||wt remove feature --force -D # Both
+$ wt remove feature --force # Remove worktree with untracked files
+$ wt remove feature -D # Delete unmerged branch
+$ wt remove feature --force -D # Both
```
Without `--force`, removal fails if the worktree contains untracked files. Without `--force-delete`, removal keeps branches with unmerged changes. Use `--no-delete-branch` to keep the branch regardless of merge status.
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index 29c60f52f..5ebfb7385 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -13,7 +13,10 @@ $ wt step commit
Manual merge workflow with review between steps:
```bash
-$ wt step commit|||wt step squash|||wt step rebase|||wt step push
+$ wt step commit
+$ wt step squash
+$ wt step rebase
+$ wt step push
```
## Operations
@@ -102,7 +105,11 @@ stage = "tracked"
Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:
```bash
-$ # Inspect the rendered prompt|||wt step commit --show-prompt | less||||||# Pipe to a different LLM|||wt step commit --show-prompt | llm -m gpt-5-nano
+# Inspect the rendered prompt
+$ wt step commit --show-prompt | less
+
+# Pipe to a different LLM
+$ wt step commit --show-prompt | llm -m gpt-5-nano
```
### Command reference
@@ -241,7 +248,9 @@ This is what `wt merge` would include — a single diff against the merge base.
Arguments after `--` are forwarded to `git diff`:
```bash
-$ wt step diff -- --stat|||wt step diff -- --name-only|||wt step diff -- -- '*.rs'
+$ wt step diff -- --stat
+$ wt step diff -- --name-only
+$ wt step diff -- -- '*.rs'
```
The diff is pipeable to tools like `delta`:
@@ -255,7 +264,9 @@ $ wt step diff | delta
Equivalent to:
```bash
-$ cp &quot;$(git rev-parse --git-dir)/index&quot; /tmp/idx|||GIT_INDEX_FILE=/tmp/idx git add --intent-to-add .|||GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state default-branch))
+$ cp "$(git rev-parse --git-dir)/index" /tmp/idx
+$ GIT_INDEX_FILE=/tmp/idx git add --intent-to-add .
+$ GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state default-branch))
```
`git diff` ignores untracked files. `git add --intent-to-add .` registers them in the index without staging their content, making them visible to `git diff`. This runs against a copy of the real index so the original is never modified.
@@ -432,30 +443,40 @@ All [hook template variables and filters](https://worktrunk.dev/hook/#template-v
Get the port for the current branch:
-<span class="cmd">wt step eval '{{ branch | hash_port }}'</span>
+```bash
+$ wt step eval '{{ branch | hash_port }}'
16066
+```
Use in shell substitution:
-<span class="cmd">curl http://localhost:$(wt step eval '{{ branch | hash_port }}')/health</span>
+```bash
+$ curl http://localhost:$(wt step eval '{{ branch | hash_port }}')/health
+```
Combine multiple values:
-<span class="cmd">wt step eval '{{ branch | hash_port }},{{ ("supabase-api-" ~ branch) | hash_port }}'</span>
+```bash
+$ wt step eval '{{ branch | hash_port }},{{ ("supabase-api-" ~ branch) | hash_port }}'
16066,16739
+```
Use conditionals and filters:
-<span class="cmd">wt step eval '{{ branch | sanitize_db }}'</span>
+```bash
+$ wt step eval '{{ branch | sanitize_db }}'
feature_auth_oauth2_a1b
+```
Show available template variables:
-<span class="cmd">wt step eval --dry-run '{{ branch }}'</span>
+```bash
+$ wt step eval --dry-run '{{ branch }}'
branch=feature/auth-oauth2
worktree_path=/home/user/projects/myapp-feature-auth-oauth2
...
Result: feature/auth-oauth2
+```
Note: This command is experimental and may change in future versions.
@@ -516,12 +537,14 @@ $ wt step for-each -- npm install
Use branch name in command:
-<span class="cmd">wt step for-each -- "echo Branch: {{ branch }}"</span>
+```bash
+$ wt step for-each -- "echo Branch: {{ branch }}"
+```
Pull updates in worktrees with upstreams (skips others):
```bash
-$ git fetch --prune && wt step for-each -- '[ &quot;$(git rev-parse @{u} 2>/dev/null)&quot; ] || exit 0; git pull --autostash'
+$ git fetch --prune && wt step for-each -- '[ "$(git rev-parse @{u} 2>/dev/null)" ] || exit 0; git pull --autostash'
```
Note: This command is experimental and may change in future versions.
@@ -563,7 +586,8 @@ Swap a branch into the main worktree. Exchanges branches and gitignored files be
### Example
```bash
-$ # from ~/project (main worktree)|||wt step promote feature
+# from ~/project (main worktree)
+$ wt step promote feature
```
Before:
@@ -642,7 +666,8 @@ Locked worktrees and the main worktree are always skipped. The current worktree
Worktrees younger than `--min-age` (default: 1 hour) are skipped. This prevents removing a worktree just created from the default branch — it looks "merged" because its branch points at the same commit.
```bash
-$ wt step prune --min-age=0s # no age guard|||wt step prune --min-age=2d # skip worktrees younger than 2 days
+$ wt step prune --min-age=0s # no age guard
+$ wt step prune --min-age=2d # skip worktrees younger than 2 days
```
### Examples
@@ -803,7 +828,10 @@ port = "echo http://localhost:{{ branch | hash_port }}"
```
```bash
-$ wt step deploy # run the alias|||wt step deploy --dry-run # show expanded command|||wt step deploy --var env=staging # pass extra template variables|||wt step deploy --yes # skip approval prompt
+$ wt step deploy # run the alias
+$ wt step deploy --dry-run # show expanded command
+$ wt step deploy --var env=staging # pass extra template variables
+$ wt step deploy --yes # skip approval prompt
```
When defined in both user and project config, both run — user first, then project. Project-config aliases require [command approval](https://worktrunk.dev/hook/#wt-hook-approvals) on first run, same as project hooks. User-config aliases are trusted.
diff --git a/skills/worktrunk/reference/switch.md b/skills/worktrunk/reference/switch.md
index 86517dffe..d358d2544 100644
--- a/skills/worktrunk/reference/switch.md
+++ b/skills/worktrunk/reference/switch.md
@@ -7,7 +7,11 @@ Worktrees are addressed by branch name; paths are computed from a configurable t
## Examples
```bash
-$ wt switch feature-auth # Switch to worktree|||wt switch - # Previous worktree (like cd -)|||wt switch --create new-feature # Create new branch and worktree|||wt switch --create hotfix --base production|||wt switch pr:123 # Switch to PR #123's branch
+$ wt switch feature-auth # Switch to worktree
+$ wt switch - # Previous worktree (like cd -)
+$ wt switch --create new-feature # Create new branch and worktree
+$ wt switch --create hotfix --base production
+$ wt switch pr:123 # Switch to PR #123's branch
```
## Creating a branch
@@ -25,7 +29,10 @@ If the branch already has a worktree, `wt switch` changes directories to it. Oth
5. Spawns [post-start](https://worktrunk.dev/hook/#hook-types) and [post-switch hooks](https://worktrunk.dev/hook/#hook-types) in the background
```bash
-$ wt switch feature # Existing branch → creates worktree|||wt switch --create feature # New branch and worktree|||wt switch --create fix --base release # New branch from release|||wt switch --create temp --no-verify # Skip hooks
+$ wt switch feature # Existing branch → creates worktree
+$ wt switch --create feature # New branch and worktree
+$ wt switch --create fix --base release # New branch from release
+$ wt switch --create temp --no-verify # Skip hooks
```
## Shortcuts
@@ -39,7 +46,11 @@ $ wt switch feature # Existing branch → creates worktre
| `mr:{N}` | GitLab MR !N's branch |
```bash
-$ wt switch - # Back to previous|||wt switch ^ # Default branch worktree|||wt switch --create fix --base=@ # Branch from current HEAD|||wt switch pr:123 # PR #123's branch|||wt switch mr:101 # MR !101's branch
+$ wt switch - # Back to previous
+$ wt switch ^ # Default branch worktree
+$ wt switch --create fix --base=@ # Branch from current HEAD
+$ wt switch pr:123 # PR #123's branch
+$ wt switch mr:101 # MR !101's branch
```
## Interactive picker
@@ -81,7 +92,8 @@ Available on Unix only (macOS, Linux). On Windows, use `wt list` or `wt switch <
The `pr:<number>` and `mr:<number>` shortcuts resolve a GitHub PR or GitLab MR to its branch. For same-repo PRs/MRs, worktrunk switches to the branch directly. For fork PRs/MRs, it fetches the ref (`refs/pull/N/head` or `refs/merge-requests/N/head`) and configures `pushRemote` to the fork URL.
```bash
-$ wt switch pr:101 # GitHub PR #101|||wt switch mr:101 # GitLab MR !101
+$ wt switch pr:101 # GitHub PR #101
+$ wt switch mr:101 # GitLab MR !101
```
Requires `gh` (GitHub) or `glab` (GitLab) CLI to be installed and authenticated. The `--create` flag cannot be used with `pr:`/`mr:` syntax since the branch already exists.
diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.md
index 98e521389..893980bc6 100644
--- a/skills/worktrunk/reference/tips-patterns.md
+++ b/skills/worktrunk/reference/tips-patterns.md
@@ -7,7 +7,9 @@ Practical recipes for common Worktrunk workflows.
Create a worktree and launch Claude in one command:
```bash
-$ alias wsc='wt switch --create --execute=claude'|||wsc new-feature # Creates worktree, runs hooks, launches Claude|||wsc feature -- 'Fix GH #322' # Runs `claude 'Fix GH #322'`
+$ alias wsc='wt switch --create --execute=claude'
+$ wsc new-feature # Creates worktree, runs hooks, launches Claude
+$ wsc feature -- 'Fix GH #322' # Runs `claude 'Fix GH #322'`
```
## Eliminate cold starts
@@ -41,7 +43,8 @@ server = "lsof -ti :{{ branch | hash_port }} -sTCP:LISTEN | xargs kill 2>/dev/nu
The URL column in `wt list` shows each worktree's dev server:
-<span class="cmd">wt list</span>
+```bash
+$ wt list
<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Remote⇅</b> <b>URL</b> <b>Commit</b> <b>Age</b>
@ main <span class=c>?</span> <span class=d>^</span><span class=d>⇅</span> <span class=g>⇡1</span> <span class=d><span class=r>⇣1</span></span> <span class=d>http://localhost:12107</span> <span class=d>41ee0834</span> <span class=d>4d</span>
+ feature-api <span class=c>+</span> <span class=d>↕</span><span class=d>⇡</span> <span class=g>+54</span> <span class=r>-5</span> <span class=g>↑4</span> <span class=d><span class=r>↓1</span></span> <span class=g>⇡3</span> <span class=d>http://localhost:10703</span> <span class=d>6814f02a</span> <span class=d>30m</span>
@@ -49,6 +52,7 @@ The URL column in `wt list` shows each worktree's dev server:
+ <span class=d>fix-typos</span> <span class=d>_</span><span class=d>|</span> <span class=d>|</span> <span class=d>http://localhost:14301</span> <span class=d>41ee0834</span> <span class=d>4d</span>
<span class=d>○</span> <span class=d>Showing 4 worktrees, 2 with changes, 2 ahead, 2 columns hidden</span>
+```
Ports are deterministic — `fix-auth` always gets port 16460, regardless of which machine or when. The URL dims if the server isn't running.
@@ -137,7 +141,9 @@ Custom emoji markers show agent state in `wt list`. The Claude Code plugin sets
Set status manually for any workflow:
```bash
-$ wt config state marker set &quot;🚧&quot; # Current branch|||wt config state marker set &quot;✅&quot; --branch feature # Specific branch|||git config worktrunk.state.feature.marker '{&quot;marker&quot;:&quot;💬&quot;,&quot;set_at&quot;:0}' # Direct
+$ wt config state marker set &quot;🚧&quot; # Current branch
+$ wt config state marker set &quot;✅&quot; --branch feature # Specific branch
+$ git config worktrunk.state.feature.marker '{&quot;marker&quot;:&quot;💬&quot;,&quot;set_at&quot;:0}' # Direct
```
See [Claude Code Integration](https://worktrunk.dev/claude-code/#installation) for plugin installation.
@@ -195,7 +201,9 @@ Reference Taskfile/Justfile/Makefile in hooks:
Special arguments work across all commands—see [`wt switch`](https://worktrunk.dev/switch/#shortcuts) for the full list.
```bash
-$ wt switch --create hotfix --base=@ # Branch from current HEAD|||wt switch - # Switch to previous worktree|||wt remove @ # Remove current worktree
+$ wt switch --create hotfix --base=@ # Branch from current HEAD
+$ wt switch - # Switch to previous worktree
+$ wt remove @ # Remove current worktree
```
## Stacked branches
@@ -214,12 +222,14 @@ Spawn a worktree with Claude running in the background:
**tmux** (new detached session):
```bash
-$ tmux new-session -d -s fix-auth-bug &quot;wt switch --create fix-auth-bug -x claude -- \||| 'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'&quot;
+$ tmux new-session -d -s fix-auth-bug &quot;wt switch --create fix-auth-bug -x claude -- \
+$ 'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'&quot;
```
**Zellij** (new pane in current session):
```bash
-$ zellij run -- wt switch --create fix-auth-bug -x claude -- \||| 'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'
+$ zellij run -- wt switch --create fix-auth-bug -x claude -- \
+$ 'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'
```
This lets one Claude session hand off work to another that runs in the background. Hooks run inside the multiplexer session/pane.
@@ -265,7 +275,9 @@ tmux = "tmux kill-session -t {{ branch | sanitize }} 2>/dev/null || true"
To create a worktree and immediately attach:
-<span class="cmd">wt switch --create feature -x 'tmux attach -t {{ branch | sanitize }}'</span>
+```bash
+$ wt switch --create feature -x 'tmux attach -t {{ branch | sanitize }}'
+```
## Xcode DerivedData cleanup
@@ -345,7 +357,8 @@ A [bare repository](https://git-scm.com/docs/gitrepository-layout) has no workin
Cloning a bare repo into `<project>/.git` puts all worktrees under one directory:
```bash
-$ git clone --bare <url> myproject/.git|||cd myproject
+$ git clone --bare <url> myproject/.git
+$ cd myproject
```
With `worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"`, worktrees become subdirectories of `myproject/`:
diff --git a/skills/worktrunk/reference/worktrunk.md b/skills/worktrunk/reference/worktrunk.md
index 497ea3f05..817ad0b54 100644
--- a/skills/worktrunk/reference/worktrunk.md
+++ b/skills/worktrunk/reference/worktrunk.md
@@ -102,7 +102,8 @@ $ cargo install worktrunk && wt config shell install
On Windows, `wt` defaults to Windows Terminal's command. Winget additionally installs Worktrunk as `git-wt` to avoid the conflict:
```bash
-$ winget install max-sixty.worktrunk|||git-wt config shell install
+$ winget install max-sixty.worktrunk
+$ git-wt config shell install
```
Alternatively, disable Windows Terminal's alias (Settings → Privacy & security → For developers → App Execution Aliases → disable "Windows Terminal") to use `wt` directly.
@@ -119,17 +120,21 @@ $ paru worktrunk-bin && wt config shell install
Create a worktree for a new feature:
-<span class="cmd">wt switch --create feature-auth</span>
+```bash
+$ wt switch --create feature-auth
<span class=g>✓</span> <span class=g>Created branch <b>feature-auth</b> from <b>main</b> and worktree @ <b>repo.feature-auth</b></span>
+```
This creates a new branch and worktree, then switches to it. Do your work, then check all worktrees with [`wt list`](https://worktrunk.dev/list/):
-<span class="cmd">wt list</span>
+```bash
+$ wt list
<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Remote⇅</b> <b>Commit</b> <b>Age</b> <b>Message</b>
@ feature-auth <span class=c>+</span> <span class=d>↑</span> <span class=g>+27</span> <span class=r>-8</span> <span class=g>↑1</span> <span class=d>4bc72dc9</span> <span class=d>2h</span> <span class=d>Add authentication module</span>
^ main <span class=d>^</span><span class=d>⇡</span> <span class=g>⇡1</span> <span class=d>0e631add</span> <span class=d>1d</span> <span class=d>Initial commit</span>
<span class=d>○</span> <span class=d>Showing 2 worktrees, 1 with changes, 1 ahead, 1 column hidden</span>
+```
The `@` marks the current worktree. `+` means staged changes, `↑1` means 1 commit ahead of main, `⇡` means unpushed commits.
@@ -138,12 +143,15 @@ When done, either:
**PR workflow** — commit, push, open a PR, merge via GitHub/GitLab, then clean up:
```bash
-$ wt step commit # commit staged changes|||gh pr create # or glab mr create|||wt remove # after PR is merged
+$ wt step commit # commit staged changes
+$ gh pr create # or glab mr create
+$ wt remove # after PR is merged
```
**Local merge** — squash, rebase onto main, fast-forward merge, clean up:
-<span class="cmd">wt merge main</span>
+```bash
+$ wt merge main
<span class=c>◎</span> <span class=c>Generating commit message and committing changes... <span style='color:var(--bright-black,#555)'>(2 files, <span class=g>+53</span></span></span>, no squashing needed<span style='color:var(--bright-black,#555)'>)</span>
<span style='background:var(--bright-white,#fff)'> </span> <b>Add authentication module</b>
<span class=g>✓</span> <span class=g>Committed changes @ <span class=d>a1b2c3d</span></span>
@@ -155,11 +163,14 @@ $ wt step commit # commit staged changes|||gh pr create
<span class=g>✓</span> <span class=g>Merged to <b>main</b> <span style='color:var(--bright-black,#555)'>(1 commit, 2 files, +53</span></span><span style='color:var(--bright-black,#555)'>)</span>
<span class=c>◎</span> <span class=c>Removing <b>feature-auth</b> worktree &amp; branch in background (same commit as <b>main</b>,</span> <span class=d>_</span><span class=c>)</span>
<span class=d>○</span> Switched to worktree for <b>main</b> @ <b>repo</b>
+```
For parallel agents, create multiple worktrees and launch an agent in each:
```bash
-$ wt switch -x claude -c feature-a -- 'Add user authentication'|||wt switch -x claude -c feature-b -- 'Fix the pagination bug'|||wt switch -x claude -c feature-c -- 'Write tests for the API'
+$ wt switch -x claude -c feature-a -- 'Add user authentication'
+$ wt switch -x claude -c feature-b -- 'Fix the pagination bug'
+$ wt switch -x claude -c feature-c -- 'Write tests for the API'
```
The `-x` flag runs a command after switching; arguments after `--` are passed to it. Configure [post-start hooks](https://worktrunk.dev/hook/) to automate setup (install deps, start dev servers).
diff --git a/src/docs.rs b/src/docs.rs
index 0ae5baf83..87942e865 100644
--- a/src/docs.rs
+++ b/src/docs.rs
@@ -9,9 +9,15 @@
/// All shell commands in `console` blocks use `$ ` prefix. This function detects
/// them and emits the appropriate shortcode form:
///
-/// - Single command, no `{{ }}`: `{{ terminal(cmd="...") }}` (Syntect highlighting)
-/// - Single command + output, no `{{ }}`: `{% terminal(cmd="...") %}output{% end %}`
-/// - Multiple commands or `{{ }}`: `{% terminal() %}` with `<span class="cmd">` body
+/// - Commands without output: `{{ terminal(cmd="...") }}` (Syntect highlighting)
+/// - Commands with output: `{% terminal(cmd="...") %}output{% end %}`
+/// - Multiple commands/comments: `|||`‐delimited in `cmd` parameter
+///
+/// `{{ }}` in commands (e.g., Jinja2 template expressions) are replaced with
+/// placeholders so Tera doesn't interpret them. The terminal shortcode template
+/// replaces them back before Syntect highlighting. Double quotes are also
+/// replaced with a placeholder since they'd close the `cmd="..."` parameter
+/// (Tera has no backslash-escape mechanism for string literals).
///
/// Blocks without `$ ` are left unchanged for the `console` → `bash` replacement.
pub fn convert_dollar_console_to_terminal(text: &str) -> String {
@@ -50,62 +56,43 @@ pub fn convert_dollar_console_to_terminal(text: &str) -> String {
continue;
}
- let has_template_syntax = commands.iter().any(|c| c.contains("{{"));
-
- if has_template_syntax {
- // {{ }} in commands — must use body approach (Tera would interpret
- // template syntax in cmd parameter). Accent color only.
- result.push_str("{% terminal() %}\n");
- for bl in &block_lines {
- if let Some(cmd) = bl.strip_prefix("$ ") {
- result.push_str("<span class=\"cmd\">");
- for ch in cmd.chars() {
- match ch {
- '<' => result.push_str("&lt;"),
- '>' => result.push_str("&gt;"),
- '&' => result.push_str("&amp;"),
- _ => result.push(ch),
- }
- }
- result.push_str("</span>\n");
+ // Use cmd parameter for Syntect highlighting on all blocks.
+ // {{ and }} are replaced with placeholders so Tera doesn't interpret
+ // them as template expressions. The terminal shortcode template
+ // replaces them back before Syntect highlighting.
+ // Multiple commands/comments joined with ||| delimiter;
+ // the template splits and highlights each individually.
+ let cmd_value: Vec<_> = block_lines
+ .iter()
+ .filter_map(|l| {
+ if let Some(cmd) = l.strip_prefix("$ ") {
+ Some(
+ cmd.replace('"', "__WT_QUOT__")
+ .replace("{{", "__WT_OPEN2__")
+ .replace("}}", "__WT_CLOSE2__"),
+ )
+ } else if l.starts_with('#') || l.is_empty() {
+ Some(l.to_string())
} else {
- result.push_str(bl);
- result.push('\n');
+ None // output lines go in body
}
- }
- result.push_str("{% end %}\n");
- } else {
- // No {{ }} — use cmd parameter for Syntect highlighting.
- // Multiple commands/comments joined with ||| delimiter;
- // the template splits and highlights each line individually.
- let cmd_value: Vec<_> = block_lines
- .iter()
- .filter_map(|l| {
- if let Some(cmd) = l.strip_prefix("$ ") {
- Some(cmd.replace('"', "&quot;"))
- } else if l.starts_with('#') || l.is_empty() {
- Some(l.to_string())
- } else {
- None // output lines go in body
- }
- })
- .collect();
- let body_lines: Vec<_> = block_lines
- .iter()
- .filter(|l| !l.starts_with("$ ") && !l.starts_with('#') && !l.is_empty())
- .collect();
+ })
+ .collect();
+ let body_lines: Vec<_> = block_lines
+ .iter()
+ .filter(|l| !l.starts_with("$ ") && !l.starts_with('#') && !l.is_empty())
+ .collect();
- let cmd_str = cmd_value.join("|||");
- if body_lines.is_empty() {
- result.push_str(&format!("{{{{ terminal(cmd=\"{cmd_str}\") }}}}\n"));
- } else {
- result.push_str(&format!("{{% terminal(cmd=\"{cmd_str}\") %}}\n"));
- for bl in &body_lines {
- result.push_str(bl);
- result.push('\n');
- }
- result.push_str("{% end %}\n");
+ let cmd_str = cmd_value.join("|||");
+ if body_lines.is_empty() {
+ result.push_str(&format!("{{{{ terminal(cmd=\"{cmd_str}\") }}}}\n"));
+ } else {
+ result.push_str(&format!("{{% terminal(cmd=\"{cmd_str}\") %}}\n"));
+ for bl in &body_lines {
+ result.push_str(bl);
+ result.push('\n');
}
+ result.push_str("{% end %}\n");
}
continue;
}
@@ -127,12 +114,11 @@ mod tests {
#[test]
fn test_convert_dollar_console_to_terminal() {
- // Command+output with {{ }} → body approach
+ // Command+output with {{ }} → cmd parameter with placeholders
assert_snapshot!(convert_dollar_console_to_terminal(
"```console\n$ wt step eval '{{ branch | hash_port }}'\n16066\n```"
), @r#"
- {% terminal() %}
- <span class="cmd">wt step eval '{{ branch | hash_port }}'</span>
+ {% terminal(cmd="wt step eval '__WT_OPEN2__ branch | hash_port __WT_CLOSE2__'") %}
16066
{% end %}
"#);
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index 4dc502386..d6b2cdd03 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -1693,11 +1693,14 @@ static ZOLA_FRONTMATTER_PATTERN: LazyLock<Regex> =
static ZOLA_TITLE_PATTERN: LazyLock<Regex> =
LazyLock::new(|| Regex::new(r#"title\s*=\s*"([^"]+)""#).unwrap());
-/// Regex to strip body-form terminal shortcodes ({% terminal(...) %}...{% end %})
-static ZOLA_TERMINAL_BODY_PATTERN: LazyLock<Regex> =
- LazyLock::new(|| Regex::new(r#"(?s)\{% terminal\([^)]*\) %\}\n?(.*?)\{% end %\}"#).unwrap());
+/// Regex to strip body-form terminal shortcodes ({% terminal(...) %}...{% end %}).
+/// Optionally captures the cmd parameter value (group 1) and body (group 2).
+static ZOLA_TERMINAL_BODY_PATTERN: LazyLock<Regex> = LazyLock::new(|| {
+ Regex::new(r#"(?s)\{%\s*terminal\((?:cmd="([^"]*)"\s*)?\)\s*%\}\n?(.*?)\{%\s*end\s*%\}"#)
+ .unwrap()
+});
-/// Regex to strip self-closing terminal shortcodes ({{ terminal(cmd="...") }})
+/// Regex to strip self-closing terminal shortcodes ({{ terminal(cmd="...") }}).
static ZOLA_TERMINAL_SELF_CLOSING_PATTERN: LazyLock<Regex> =
LazyLock::new(|| Regex::new(r#"\{\{ terminal\(cmd="([^"]*)"\) \}\}"#).unwrap());
@@ -1714,6 +1717,43 @@ static AUTO_GENERATED_MARKER_PATTERN: LazyLock<Regex> = LazyLock::new(|| {
static HTML_FIGURE_PATTERN: LazyLock<Regex> =
LazyLock::new(|| Regex::new(r"(?s)<figure[^>]*>.*?</figure>\n*").unwrap());
+/// Regex to strip `<span class="cmd">...</span>` lines from shortcode bodies.
+/// These duplicate the cmd parameter content (the template uses `clean_body` for this).
+static SPAN_CMD_PATTERN: LazyLock<Regex> =
+ LazyLock::new(|| Regex::new(r#"<span class="cmd">[^<]*</span>\n?"#).unwrap());
+
+/// Regex to convert `<span class="cmd">X</span>` → `$ X` for no-cmd body shortcodes.
+static SPAN_CMD_TO_DOLLAR: LazyLock<Regex> =
+ LazyLock::new(|| Regex::new(r#"<span class="cmd">([^<]*)</span>"#).unwrap());
+
+/// Convert a `|||`-delimited cmd string (and optional body) into a ```bash block.
+/// Each cmd line gets `$ ` prefix; comment lines (`#`) and blank lines pass through.
+fn cmd_to_bash_block(cmd: &str, body: &str) -> String {
+ let mut result = String::from("```bash\n");
+ for line in cmd.split("|||") {
+ if line.is_empty() {
+ result.push('\n');
+ } else if line.starts_with('#') {
+ result.push_str(line);
+ result.push('\n');
+ } else {
+ result.push_str("$ ");
+ result.push_str(line);
+ result.push('\n');
+ }
+ }
+ // Strip <span class="cmd"> lines that duplicate the cmd parameter
+ let clean_body = SPAN_CMD_PATTERN.replace_all(body, "");
+ if !clean_body.is_empty() {
+ result.push_str(&clean_body);
+ if !clean_body.ends_with('\n') {
+ result.push('\n');
+ }
+ }
+ result.push_str("```");
+ result
+}
+
/// Transform docs content for skill file consumption
///
/// Transforms:
@@ -1736,11 +1776,30 @@ fn transform_docs_for_skill(content: &str) -> String {
// Strip frontmatter
let content = ZOLA_FRONTMATTER_PATTERN.replace(content, "");
- // Strip terminal shortcodes:
- // - Body form: keep inner content
- // - Self-closing: convert to `$ command` (plain text with prompt)
- let content = ZOLA_TERMINAL_BODY_PATTERN.replace_all(&content, "$1");
- let content = ZOLA_TERMINAL_SELF_CLOSING_PATTERN.replace_all(&content, "```bash\n$$ $1\n```");
+ // Strip terminal shortcodes, converting cmd parameters back to `$ command` blocks.
+ // Commands joined by `|||` are split into separate lines.
+ let content = ZOLA_TERMINAL_BODY_PATTERN.replace_all(&content, |caps: &regex::Captures| {
+ let body = caps.get(2).map_or("", |m| m.as_str());
+ match caps.get(1) {
+ Some(cmd) => cmd_to_bash_block(cmd.as_str(), body),
+ None if body.contains(r#"<span class="cmd">"#) => {
+ // Old-style body shortcode with <span class="cmd"> — convert to $ lines
+ let converted = SPAN_CMD_TO_DOLLAR.replace_all(body, "$$ $1");
+ format!("```bash\n{converted}```")
+ }
+ None => body.to_string(),
+ }
+ });
+ let content = ZOLA_TERMINAL_SELF_CLOSING_PATTERN
+ .replace_all(&content, |caps: &regex::Captures| {
+ cmd_to_bash_block(caps.get(1).map_or("", |m| m.as_str()), "")
+ });
+
+ // Replace placeholders used to escape Tera template syntax in cmd parameters
+ let content = content
+ .replace("__WT_OPEN2__", "{{")
+ .replace("__WT_CLOSE2__", "}}")
+ .replace("__WT_QUOT__", "\"");
// Strip AUTO-GENERATED marker comments (keep content)
let content = AUTO_GENERATED_MARKER_PATTERN.replace_all(&content, "");