Skip to content

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.md
index 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.md
index 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.md
index 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.md
index 434f2b1c2..ba0f4193c 100644
--- a/docs/content/llm-commits.md
+++ b/docs/content/llm-commits.md
@@ -89,7 +89,9 @@ $ wt step squash
See [`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.md
index 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]</spa
Verbose 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]</span
Verbose 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]</spa
Verbose 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.scss
index 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.md
index 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.md
index 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.md
index 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.md
index 230e0bea1..d5baf97e6 100644
--- a/skills/worktrunk/reference/llm-commits.md
+++ b/skills/worktrunk/reference/llm-commits.md
@@ -75,7 +75,9 @@ $ wt step squash
See [`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.md
index 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.rs
index 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());