Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
fix: place experimental badge outside heading anchor links (#1742)
Maximilian Roos5cf6c0eac317
diff --git a/docs/content/config.md b/docs/content/config.mdindex 5719f425b..66ad5ba84 100644--- a/docs/content/config.md+++ b/docs/content/config.md@@ -239,7 +239,9 @@ For context:Entries are keyed by project identifier (e.g., `github.com/user/repo`).-#### Setting overrides <span class="badge-experimental"></span>+#### Setting overrides++<span class="badge-experimental"></span>Override global user config for a specific project. Scalar values (like `worktree-path`) replace the global value; everything else (hooks, aliases, etc.) appends, global first.diff --git a/docs/content/hook.md b/docs/content/hook.mdindex 98c15f148..0f47a226f 100644--- a/docs/content/hook.md+++ b/docs/content/hook.md@@ -306,7 +306,9 @@ The `user:` and `project:` prefixes filter by source. Use `user:` or `project:`The `--var KEY=VALUE` flag overrides built-in template variables — useful for testing hooks with different contexts without switching to that context.-# Pipeline Ordering <span class="badge-experimental"></span>+# Pipeline Ordering++<span class="badge-experimental"></span>By default, all commands in a `post-*` hook run concurrently in the background. When one command depends on another — `npm run build` needs `npm install` to finish first — use a list instead of a table:diff --git a/docs/content/list.md b/docs/content/list.mdindex 8451ecb49..b1c5e16bc 100644--- a/docs/content/list.md+++ b/docs/content/list.md@@ -117,7 +117,9 @@ The CI column shows GitHub/GitLab pipeline status:CI indicators are clickable links to the PR or pipeline page. Any CI dot appears dimmed when there are unpushed local changes (stale status). PRs/MRs are checked first, then branch workflows/pipelines for branches with an upstream. Local-only branches show blank; remote-only branches (visible with `--remotes`) get CI status detection. Results are cached for 30-60 seconds; use `wt config state` to view or clear.-### LLM summaries <span class="badge-experimental"></span>+### LLM summaries++<span class="badge-experimental"></span>Reuses the [`commit.generation`](@/config.md#commit) command — the same LLM that generates commit messages. Enable with `summary = true` in `[list]` config; requires `--full`. Results are cached until the branch's diff changes.diff --git a/docs/content/llm-commits.md b/docs/content/llm-commits.mdindex 434f2b1c2..ba0f4193c 100644--- a/docs/content/llm-commits.md+++ b/docs/content/llm-commits.md@@ -89,7 +89,9 @@ $ wt step squashSee [`wt merge`](@/merge.md) and [`wt step`](@/step.md) for full documentation.-## Branch summaries <span class="badge-experimental"></span>+## Branch summaries++<span class="badge-experimental"></span>With `summary = true` and a `[commit.generation] command` configured, Worktrunk generates LLM branch summaries — one-line descriptions of each branch's changes since the default branch.diff --git a/docs/content/step.md b/docs/content/step.mdindex 02541fd6f..699a3ea0f 100644--- a/docs/content/step.md+++ b/docs/content/step.md@@ -458,7 +458,9 @@ Usage: <b><span class=c>wt step copy-ignored</span></b> <span class=c>[OPTIONS]<Verbose output (-v: hooks, templates; -vv: debug report){% end %}-## wt step eval <span class="badge-experimental"></span>+## wt step eval++<span class="badge-experimental"></span>Evaluate a template expression. Prints the result to stdout for use in scripts and shell substitutions.@@ -536,7 +538,9 @@ Usage: <b><span class=c>wt step eval</span></b> <span class=c>[OPTIONS]</span> <Verbose output (-v: hooks, templates; -vv: debug report){% end %}-## wt step for-each <span class="badge-experimental"></span>+## wt step for-each++<span class="badge-experimental"></span>Run command in each worktree. Executes sequentially with real-time output; continues on failure.@@ -602,7 +606,9 @@ Usage: <b><span class=c>wt step for-each</span></b> <span class=c>[OPTIONS]</spaVerbose output (-v: hooks, templates; -vv: debug report){% end %}-## wt step promote <span class="badge-experimental"></span>+## wt step promote++<span class="badge-experimental"></span>Swap a branch into the main worktree. Exchanges branches and gitignored files between two worktrees.@@ -676,7 +682,9 @@ Usage: <b><span class=c>wt step promote</span></b> <span class=c>[OPTIONS]</spanVerbose output (-v: hooks, templates; -vv: debug report){% end %}-## wt step prune <span class="badge-experimental"></span>+## wt step prune++<span class="badge-experimental"></span>Remove worktrees merged into the default branch.@@ -746,7 +754,9 @@ Usage: <b><span class=c>wt step prune</span></b> <span class=c>[OPTIONS]</span>Verbose output (-v: hooks, templates; -vv: debug report){% end %}-## wt step relocate <span class="badge-experimental"></span>+## wt step relocate++<span class="badge-experimental"></span>Move worktrees to expected paths. Relocates worktrees whose path doesn't match the worktree-path template.@@ -841,7 +851,9 @@ Usage: <b><span class=c>wt step relocate</span></b> <span class=c>[OPTIONS]</spaVerbose output (-v: hooks, templates; -vv: debug report){% end %}-## Aliases <span class="badge-experimental"></span>+## Aliases++<span class="badge-experimental"></span>Custom command templates configured in user config (`~/.config/worktrunk/config.toml`) or project config (`.config/wt.toml`). Aliases support the same [template variables](@/hook.md#template-variables) as hooks.diff --git a/docs/sass/custom.scss b/docs/sass/custom.scssindex e3a079271..6deece637 100644--- a/docs/sass/custom.scss+++ b/docs/sass/custom.scss@@ -997,7 +997,7 @@ ul > li::marker {// Zola's heading slug generation or page TOC entries..badge-experimental {display: inline-block;- vertical-align: middle;+ vertical-align: 0.15em;white-space: nowrap;&::after {@@ -1013,6 +1013,18 @@ ul > li::marker {}}+// Badge after heading — generated on a separate line so Zola's anchor link+// doesn't wrap it. The badge lands in a <p> (CommonMark wraps inline HTML);+// collapse that <p> to inline so it flows on the heading's line.+:is(h1, h2, h3, h4):has(+ p > .badge-experimental:only-child) {+ display: inline-block;+}++:is(h1, h2, h3, h4) + p:has(> .badge-experimental:only-child) {+ display: inline;+ margin: 0;+}+// ============================================================================// Figures// ============================================================================diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.mdindex 8bbeb993b..6847149e9 100644--- a/skills/worktrunk/reference/config.md+++ b/skills/worktrunk/reference/config.md@@ -230,7 +230,9 @@ For context:Entries are keyed by project identifier (e.g., `github.com/user/repo`).-#### Setting overrides [experimental]+#### Setting overrides++[experimental]Override global user config for a specific project. Scalar values (like `worktree-path`) replace the global value; everything else (hooks, aliases, etc.) appends, global first.diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.mdindex c05951aed..a0c4d6166 100644--- a/skills/worktrunk/reference/hook.md+++ b/skills/worktrunk/reference/hook.md@@ -297,7 +297,9 @@ The `user:` and `project:` prefixes filter by source. Use `user:` or `project:`The `--var KEY=VALUE` flag overrides built-in template variables — useful for testing hooks with different contexts without switching to that context.-# Pipeline Ordering [experimental]+# Pipeline Ordering++[experimental]By default, all commands in a `post-*` hook run concurrently in the background. When one command depends on another — `npm run build` needs `npm install` to finish first — use a list instead of a table:diff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.mdindex e3818217f..9123138ca 100644--- a/skills/worktrunk/reference/list.md+++ b/skills/worktrunk/reference/list.md@@ -89,7 +89,9 @@ The CI column shows GitHub/GitLab pipeline status:CI indicators are clickable links to the PR or pipeline page. Any CI dot appears dimmed when there are unpushed local changes (stale status). PRs/MRs are checked first, then branch workflows/pipelines for branches with an upstream. Local-only branches show blank; remote-only branches (visible with `--remotes`) get CI status detection. Results are cached for 30-60 seconds; use `wt config state` to view or clear.-### LLM summaries [experimental]+### LLM summaries++[experimental]Reuses the [`commit.generation`](https://worktrunk.dev/config/#commit) command — the same LLM that generates commit messages. Enable with `summary = true` in `[list]` config; requires `--full`. Results are cached until the branch's diff changes.diff --git a/skills/worktrunk/reference/llm-commits.md b/skills/worktrunk/reference/llm-commits.mdindex 230e0bea1..d5baf97e6 100644--- a/skills/worktrunk/reference/llm-commits.md+++ b/skills/worktrunk/reference/llm-commits.md@@ -75,7 +75,9 @@ $ wt step squashSee [`wt merge`](https://worktrunk.dev/merge/) and [`wt step`](https://worktrunk.dev/step/) for full documentation.-## Branch summaries [experimental]+## Branch summaries++[experimental]With `summary = true` and a `[commit.generation] command` configured, Worktrunk generates LLM branch summaries — one-line descriptions of each branch's changes since the default branch.diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.mdindex 191deca24..b97489433 100644--- a/skills/worktrunk/reference/step.md+++ b/skills/worktrunk/reference/step.md@@ -434,7 +434,9 @@ Usage: <b><span class=c>wt step copy-ignored</span></b> <span class=c>[OPTIONS]<<b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>Verbose output (-v: hooks, templates; -vv: debug report)-## wt step eval [experimental]+## wt step eval++[experimental]Evaluate a template expression. Prints the result to stdout for use in scripts and shell substitutions.@@ -510,7 +512,9 @@ Usage: <b><span class=c>wt step eval</span></b> <span class=c>[OPTIONS]</span> <<b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>Verbose output (-v: hooks, templates; -vv: debug report)-## wt step for-each [experimental]+## wt step for-each++[experimental]Run command in each worktree. Executes sequentially with real-time output; continues on failure.@@ -574,7 +578,9 @@ Usage: <b><span class=c>wt step for-each</span></b> <span class=c>[OPTIONS]</spa<b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>Verbose output (-v: hooks, templates; -vv: debug report)-## wt step promote [experimental]+## wt step promote++[experimental]Swap a branch into the main worktree. Exchanges branches and gitignored files between two worktrees.@@ -646,7 +652,9 @@ Usage: <b><span class=c>wt step promote</span></b> <span class=c>[OPTIONS]</span<b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>Verbose output (-v: hooks, templates; -vv: debug report)-## wt step prune [experimental]+## wt step prune++[experimental]Remove worktrees merged into the default branch.@@ -714,7 +722,9 @@ Usage: <b><span class=c>wt step prune</span></b> <span class=c>[OPTIONS]</span><b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>Verbose output (-v: hooks, templates; -vv: debug report)-## wt step relocate [experimental]+## wt step relocate++[experimental]Move worktrees to expected paths. Relocates worktrees whose path doesn't match the worktree-path template.@@ -807,7 +817,9 @@ Usage: <b><span class=c>wt step relocate</span></b> <span class=c>[OPTIONS]</spa<b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>Verbose output (-v: hooks, templates; -vv: debug report)-## Aliases [experimental]+## Aliases++[experimental]Custom command templates configured in user config (`~/.config/worktrunk/config.toml`) or project config (`.config/wt.toml`). Aliases support the same [template variables](https://worktrunk.dev/hook/#template-variables) as hooks.diff --git a/src/help.rs b/src/help.rsindex cd56b1f67..f7bf0bbc1 100644--- a/src/help.rs+++ b/src/help.rs@@ -436,6 +436,11 @@ Commands with pages: merge, switch, remove, list"////// The terminal counterpart is `md_help::colorize_status_symbols()`.fn post_process_for_html(text: &str) -> String {+ // First pass: move [experimental] from heading lines to a separate line after+ // the heading. This keeps the badge outside Zola's heading anchor link.+ // Terminal help keeps [experimental] on the heading line (different render path).+ let text = move_experimental_from_headings(text);+text// CI status colors (in table cells).replace("`●` green", "<span style='color:#0a0'>●</span> green")@@ -459,6 +464,49 @@ fn post_process_for_html(text: &str) -> String {)}+/// Move `[experimental]` from heading lines to a separate line after the heading.+///+/// Transforms `## Foo [experimental]` into:+/// ```text+/// ## Foo+///+/// [experimental]+/// ```+///+/// This keeps the badge outside Zola's `<a class="zola-anchor">` wrapper so it's+/// not part of the heading link. The `[experimental]` is then replaced with the+/// badge `<span>` by the caller's `.replace()` chain.+fn move_experimental_from_headings(text: &str) -> String {+ if !text.contains(" [experimental]") {+ return text.to_string();+ }++ let mut result = String::with_capacity(text.len());+ let mut in_code_block = false;++ for line in text.lines() {+ if line.trim_start().starts_with("```") {+ in_code_block = !in_code_block;+ }++ if !in_code_block+ && line.starts_with('#')+ && let Some(heading) = line.strip_suffix(" [experimental]")+ {+ result.push_str(heading);+ result.push_str("\n\n[experimental]");+ } else {+ result.push_str(line);+ }+ result.push('\n');+ }+ // .lines() strips the trailing newline; restore original behavior+ if !text.ends_with('\n') {+ result.pop();+ }+ result+}+/// Increase markdown heading levels by one (## -> ###, ### -> ####, etc.)////// This makes subdoc headings children of the subdoc's main heading.@@ -576,16 +624,14 @@ fn format_subcommand_section(let raw_help = combine_command_docs(sub);let raw_help = raw_help.replace("```console\n", "```bash\n");- // Extract [experimental] marker from content start → badge on heading instead.- // The badge span is empty — text comes from CSS ::after — so it doesn't affect- // Zola's heading slug generation or page TOC entries.- let (heading_badge, raw_help) = if let Some(rest) = raw_help.strip_prefix("[experimental] ") {- (- " <span class=\"badge-experimental\"></span>",- rest.to_string(),- )+ // Extract [experimental] marker from content start → badge after heading.+ // Placed after the heading (not inside it) so Zola's anchor link doesn't+ // wrap the badge. CSS positions it inline with the heading text.+ let (has_experimental, raw_help) = if let Some(rest) = raw_help.strip_prefix("[experimental] ")+ {+ (true, rest.to_string())} else {- ("", raw_help)+ (false, raw_help)};// Split content at first subdoc placeholder so command reference comes before nested subdocs@@ -613,8 +659,11 @@ fn format_subcommand_section(// Get help reference (wrap at 80 chars for web docs, with colors for HTML)let reference_block = help_reference(&command_path, Some(80));- // Format the section: heading, main content, command reference, then nested subdocs- let mut section = format!("## {full_command}{heading_badge}\n\n");+ // Format the section: heading, badge (outside heading), main content, command reference+ let mut section = format!("## {full_command}\n\n");+ if has_experimental {+ section.push_str("<span class=\"badge-experimental\"></span>\n\n");+ }if !main_help.is_empty() {section.push_str(main_help.trim());