Skip to content

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

feat(docs): move experimental badges to headings (#1523)

Maximilian Roos879cbd906b57
diff --git a/README.md b/README.md
index b1abb431d..23c7e626e 100644
--- a/README.md
+++ b/README.md
@@ -87,7 +87,7 @@ git branch -d feat</pre></td>
- **[Merge workflow](https://worktrunk.dev/merge/)** — squash, rebase, merge, clean up in one command
- **[Interactive picker](https://worktrunk.dev/switch/#interactive-picker)** — browse worktrees with live diff and log previews
- **[Copy build caches](https://worktrunk.dev/step/)** — skip cold starts by sharing `target/`, `node_modules/`, etc between worktrees
-- **[`wt list --full`](https://worktrunk.dev/list/#full-mode)** — [CI status](https://worktrunk.dev/list/#ci-status) and [AI-generated summaries](https://worktrunk.dev/list/#llm-summaries-experimental) per branch
+- **[`wt list --full`](https://worktrunk.dev/list/#full-mode)** — [CI status](https://worktrunk.dev/list/#ci-status) and [AI-generated summaries](https://worktrunk.dev/list/#llm-summaries) per branch
- **[PR checkout](https://worktrunk.dev/switch/#github-pull-requests)** — `wt switch pr:123` to jump straight to a PR's branch
- **[Dev server per worktree](https://worktrunk.dev/hook/#dev-servers)** — `hash_port` template filter gives each worktree a unique port
- ...and **[lots more](#next-steps)**
diff --git a/docs/content/config.md b/docs/content/config.md
index f5a6977a6..5422943e2 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -190,7 +190,7 @@ For context:
Entries are keyed by project identifier (e.g., `github.com/user/repo`).
-#### Setting overrides <span class="badge-experimental">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. Hooks append — both global and per-project hooks run. Aliases merge — per-project aliases override global aliases on name collision.
diff --git a/docs/content/faq.md b/docs/content/faq.md
index f11799a8e..f281e974b 100644
--- a/docs/content/faq.md
+++ b/docs/content/faq.md
@@ -166,7 +166,7 @@ Worktrunk runs `git` commands internally and optionally runs `gh` (GitHub) or `g
1. **User hooks** (`~/.config/worktrunk/config.toml`) — Personal automation for all repositories
2. **Project hooks** (`.config/wt.toml`) — Repository-specific automation
-3. **LLM commands** (`~/.config/worktrunk/config.toml`) — Commit message generation and [branch summaries](@/llm-commits.md#branch-summaries-experimental)
+3. **LLM commands** (`~/.config/worktrunk/config.toml`) — Commit message generation and [branch summaries](@/llm-commits.md#branch-summaries)
4. **--execute flag** — Explicitly provided commands
User hooks don't require approval (you defined them). Commands from project hooks require approval on first run. Approved commands are saved to user config. If a command changes, Worktrunk requires new approval.
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 57e43dcbb..35eacc57f 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -167,7 +167,7 @@ build = "cargo build --release"
## User hooks
-Define hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval. For repository-specific user hooks, see [setting overrides](@/config.md#setting-overrides-experimental).
+Define hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval. For repository-specific user hooks, see [setting overrides](@/config.md#setting-overrides).
```toml
# ~/.config/worktrunk/config.toml
diff --git a/docs/content/list.md b/docs/content/list.md
index 42941404a..8451ecb49 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -24,7 +24,7 @@ The table renders progressively: branch names, paths, and commit hashes appear i
## Full mode
-`--full` adds columns that require network access or LLM calls: [CI status](#ci-status) (GitHub/GitLab pipeline pass/fail), line diffs since the merge-base, and [LLM-generated summaries](#llm-summaries-experimental) of each branch's changes. The table displays instantly and columns fill in as results arrive.
+`--full` adds columns that require network access or LLM calls: [CI status](#ci-status) (GitHub/GitLab pipeline pass/fail), line diffs since the merge-base, and [LLM-generated summaries](#llm-summaries) of each branch's changes. The table displays instantly and columns fill in as results arrive.
## Examples
@@ -90,7 +90,7 @@ $ wt list --format=json
| HEAD± | Uncommitted changes: +added -deleted lines |
| main↕ | Commits ahead/behind default branch |
| main…± | Line diffs since the merge-base with the default branch (`--full`) |
-| Summary | LLM-generated branch summary (`--full` + `summary = true`, requires [`commit.generation`](@/config.md#commit)) <span class="badge-experimental">experimental</span> |
+| Summary | LLM-generated branch summary (`--full` + `summary = true`, requires [`commit.generation`](@/config.md#commit)) <span class="badge-experimental"></span> |
| Remote⇅ | Commits ahead/behind tracking branch |
| CI | Pipeline status (`--full`) |
| Path | Worktree directory |
@@ -117,7 +117,7 @@ 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">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 02ec1aa27..434f2b1c2 100644
--- a/docs/content/llm-commits.md
+++ b/docs/content/llm-commits.md
@@ -89,14 +89,14 @@ $ wt step squash
See [`wt merge`](@/merge.md) and [`wt step`](@/step.md) for full documentation.
-## Branch summaries <span class="badge-experimental">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.
Summaries appear in:
- **`wt switch`** [interactive picker](@/switch.md#interactive-picker) — preview tab 5
-- **`wt list --full`** — the Summary column (see [`wt list`](@/list.md#llm-summaries-experimental))
+- **`wt list --full`** — the Summary column (see [`wt list`](@/list.md#llm-summaries))
Enable in user config:
diff --git a/docs/content/step.md b/docs/content/step.md
index 53f63a506..9130e149c 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -36,11 +36,11 @@ wt step push
- `push` — Fast-forward target to current branch
- [`diff`](#wt-step-diff) — Show all changes since branching (committed, staged, unstaged, untracked)
- [`copy-ignored`](#wt-step-copy-ignored) — Copy gitignored files between worktrees
-- [`for-each`](#wt-step-for-each) — <span class="badge-experimental">experimental</span> Run a command in every worktree
-- [`promote`](#wt-step-promote) — <span class="badge-experimental">experimental</span> Swap a branch into the main worktree
+- [`for-each`](#wt-step-for-each) — <span class="badge-experimental"></span> Run a command in every worktree
+- [`promote`](#wt-step-promote) — <span class="badge-experimental"></span> Swap a branch into the main worktree
- [`prune`](#wt-step-prune) — Remove worktrees and branches merged into the default branch
-- [`relocate`](#wt-step-relocate) — <span class="badge-experimental">experimental</span> Move worktrees to expected paths
-- [`<alias>`](#aliases) — <span class="badge-experimental">experimental</span> Run a configured command alias
+- [`relocate`](#wt-step-relocate) — <span class="badge-experimental"></span> Move worktrees to expected paths
+- [`<alias>`](#aliases) — <span class="badge-experimental"></span> Run a configured command alias
## See also
@@ -451,9 +451,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 for-each
+## wt step for-each <span class="badge-experimental"></span>
-<span class="badge-experimental">experimental</span> Run command in each worktree. Executes sequentially with real-time output; continues on failure.
+Run command in each worktree. Executes sequentially with real-time output; continues on failure.
Executes a command sequentially in every worktree with real-time output. Continues on failure and shows a summary at the end.
@@ -519,9 +519,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
+## wt step promote <span class="badge-experimental"></span>
-<span class="badge-experimental">experimental</span> Swap a branch into the main worktree. Exchanges branches and gitignored files between two worktrees.
+Swap a branch into the main worktree. Exchanges branches and gitignored files between two worktrees.
**Experimental.** Use promote for temporary testing when the main worktree has special significance (Docker Compose, IDE configs, heavy build artifacts anchored to project root), and hooks & tools aren't yet set up to run on arbitrary worktrees. The idiomatic Worktrunk workflow does not use `promote`; instead each worktree has a full environment. `promote` is the only Worktrunk command which changes a branch in an existing worktree.
@@ -593,9 +593,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
+## wt step prune <span class="badge-experimental"></span>
-<span class="badge-experimental">experimental</span> Remove worktrees merged into the default branch.
+Remove worktrees merged into the default branch.
Bulk-removes worktrees and branches that are integrated into the default branch, using the same criteria as `wt remove`'s branch cleanup. Stale worktree entries are cleaned up too.
@@ -663,9 +663,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
+## wt step relocate <span class="badge-experimental"></span>
-<span class="badge-experimental">experimental</span> Move worktrees to expected paths. Relocates worktrees whose path doesn't match the worktree-path template.
+Move worktrees to expected paths. Relocates worktrees whose path doesn't match the worktree-path template.
Moves worktrees to match the configured `worktree-path` template.
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index 1d1f42f57..491a54c36 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -176,7 +176,7 @@ With `summary = true` and [`commit.generation`](@/config.md#commit) configured,
summary = true
```
-Disabled by default — when enabled, each branch's diff is sent to the configured LLM for summarization. See [LLM Commits](@/llm-commits.md#branch-summaries-experimental) for details.
+Disabled by default — when enabled, each branch's diff is sent to the configured LLM for summarization. See [LLM Commits](@/llm-commits.md#branch-summaries) for details.
## JSON API
diff --git a/docs/content/worktrunk.md b/docs/content/worktrunk.md
index 3ff717731..3a24d29f7 100644
--- a/docs/content/worktrunk.md
+++ b/docs/content/worktrunk.md
@@ -88,7 +88,7 @@ git branch -d feat{% end %}</td>
- **[Merge workflow](@/merge.md)** — squash, rebase, merge, clean up in one command
- **[Interactive picker](@/switch.md#interactive-picker)** — browse worktrees with live diff and log previews
- **[Copy build caches](@/step.md)** — skip cold starts by sharing `target/`, `node_modules/`, etc between worktrees
-- **[`wt list --full`](@/list.md#full-mode)** — [CI status](@/list.md#ci-status) and [AI-generated summaries](@/list.md#llm-summaries-experimental) per branch
+- **[`wt list --full`](@/list.md#full-mode)** — [CI status](@/list.md#ci-status) and [AI-generated summaries](@/list.md#llm-summaries) per branch
- **[PR checkout](@/switch.md#github-pull-requests)** — `wt switch pr:123` to jump straight to a PR's branch
- **[Dev server per worktree](@/hook.md#dev-servers)** — `hash_port` template filter gives each worktree a unique port
- ...and **[lots more](#next-steps)**
diff --git a/docs/sass/custom.scss b/docs/sass/custom.scss
index dc499e8b6..e3a079271 100644
--- a/docs/sass/custom.scss
+++ b/docs/sass/custom.scss
@@ -993,21 +993,24 @@ ul > li::marker {
// Badges — status labels (experimental, deprecated, etc.)
// ============================================================================
-// Experimental badge — quiet label, reads as metadata not emphasis
+// Experimental badge — empty span, text via ::after so it doesn't affect
+// Zola's heading slug generation or page TOC entries.
.badge-experimental {
display: inline-block;
- font-size: 0.65rem;
- font-weight: 600;
- text-transform: uppercase;
- letter-spacing: 0.04em;
- color: var(--wt-color-text-soft);
- border: 1px solid var(--wt-color-border-subtle);
- border-radius: var(--wt-radius-pill);
- padding: 0.05rem 0.5rem;
vertical-align: middle;
white-space: nowrap;
- line-height: 1.4;
+ &::after {
+ content: "EXPERIMENTAL";
+ font-size: 0.65rem;
+ font-weight: 600;
+ letter-spacing: 0.04em;
+ color: var(--wt-color-text-soft);
+ border: 1px solid var(--wt-color-border-subtle);
+ border-radius: var(--wt-radius-pill);
+ padding: 0.05rem 0.5rem;
+ line-height: 1.4;
+ }
}
// ============================================================================
diff --git a/docs/templates/shortcodes/experimental.html b/docs/templates/shortcodes/experimental.html
index 44bfd92b5..580e796fe 100644
--- a/docs/templates/shortcodes/experimental.html
+++ b/docs/templates/shortcodes/experimental.html
@@ -1 +1 @@
-<span class="badge-experimental">experimental</span>
+<span class="badge-experimental"></span>
diff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.md
index a6b953ae4..070de9b51 100644
--- a/skills/worktrunk/reference/faq.md
+++ b/skills/worktrunk/reference/faq.md
@@ -159,7 +159,7 @@ Worktrunk runs `git` commands internally and optionally runs `gh` (GitHub) or `g
1. **User hooks** (`~/.config/worktrunk/config.toml`) — Personal automation for all repositories
2. **Project hooks** (`.config/wt.toml`) — Repository-specific automation
-3. **LLM commands** (`~/.config/worktrunk/config.toml`) — Commit message generation and [branch summaries](https://worktrunk.dev/llm-commits/#branch-summaries-experimental)
+3. **LLM commands** (`~/.config/worktrunk/config.toml`) — Commit message generation and [branch summaries](https://worktrunk.dev/llm-commits/#branch-summaries)
4. **--execute flag** — Explicitly provided commands
User hooks don't require approval (you defined them). Commands from project hooks require approval on first run. Approved commands are saved to user config. If a command changes, Worktrunk requires new approval.
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index fffa8f2bb..3a3fac877 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -158,7 +158,7 @@ build = "cargo build --release"
## User hooks
-Define hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval. For repository-specific user hooks, see [setting overrides](https://worktrunk.dev/config/#setting-overrides-experimental).
+Define hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval. For repository-specific user hooks, see [setting overrides](https://worktrunk.dev/config/#setting-overrides).
```toml
# ~/.config/worktrunk/config.toml
diff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.md
index 0c4412a5d..e3818217f 100644
--- a/skills/worktrunk/reference/list.md
+++ b/skills/worktrunk/reference/list.md
@@ -8,7 +8,7 @@ The table renders progressively: branch names, paths, and commit hashes appear i
## Full mode
-`--full` adds columns that require network access or LLM calls: [CI status](#ci-status) (GitHub/GitLab pipeline pass/fail), line diffs since the merge-base, and [LLM-generated summaries](#llm-summaries-experimental) of each branch's changes. The table displays instantly and columns fill in as results arrive.
+`--full` adds columns that require network access or LLM calls: [CI status](#ci-status) (GitHub/GitLab pipeline pass/fail), line diffs since the merge-base, and [LLM-generated summaries](#llm-summaries) of each branch's changes. The table displays instantly and columns fill in as results arrive.
## Examples
diff --git a/skills/worktrunk/reference/llm-commits.md b/skills/worktrunk/reference/llm-commits.md
index f1c17c2aa..230e0bea1 100644
--- a/skills/worktrunk/reference/llm-commits.md
+++ b/skills/worktrunk/reference/llm-commits.md
@@ -82,7 +82,7 @@ With `summary = true` and a `[commit.generation] command` configured, Worktrunk
Summaries appear in:
- **`wt switch`** [interactive picker](https://worktrunk.dev/switch/#interactive-picker) — preview tab 5
-- **`wt list --full`** — the Summary column (see [`wt list`](https://worktrunk.dev/list/#llm-summaries-experimental))
+- **`wt list --full`** — the Summary column (see [`wt list`](https://worktrunk.dev/list/#llm-summaries))
Enable in user config:
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index ebb79cfdb..4d5e5e0f6 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -427,9 +427,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 for-each
+## wt step for-each [experimental]
-[experimental] Run command in each worktree. Executes sequentially with real-time output; continues on failure.
+Run command in each worktree. Executes sequentially with real-time output; continues on failure.
Executes a command sequentially in every worktree with real-time output. Continues on failure and shows a summary at the end.
@@ -493,9 +493,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
+## wt step promote [experimental]
-[experimental] Swap a branch into the main worktree. Exchanges branches and gitignored files between two worktrees.
+Swap a branch into the main worktree. Exchanges branches and gitignored files between two worktrees.
**Experimental.** Use promote for temporary testing when the main worktree has special significance (Docker Compose, IDE configs, heavy build artifacts anchored to project root), and hooks & tools aren't yet set up to run on arbitrary worktrees. The idiomatic Worktrunk workflow does not use `promote`; instead each worktree has a full environment. `promote` is the only Worktrunk command which changes a branch in an existing worktree.
@@ -565,9 +565,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
+## wt step prune [experimental]
-[experimental] Remove worktrees merged into the default branch.
+Remove worktrees merged into the default branch.
Bulk-removes worktrees and branches that are integrated into the default branch, using the same criteria as `wt remove`'s branch cleanup. Stale worktree entries are cleaned up too.
@@ -633,9 +633,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
+## wt step relocate [experimental]
-[experimental] Move worktrees to expected paths. Relocates worktrees whose path doesn't match the worktree-path template.
+Move worktrees to expected paths. Relocates worktrees whose path doesn't match the worktree-path template.
Moves worktrees to match the configured `worktree-path` template.
diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.md
index f7849e572..f594d2fd2 100644
--- a/skills/worktrunk/reference/tips-patterns.md
+++ b/skills/worktrunk/reference/tips-patterns.md
@@ -165,7 +165,7 @@ With `summary = true` and [`commit.generation`](https://worktrunk.dev/config/#co
summary = true
```
-Disabled by default — when enabled, each branch's diff is sent to the configured LLM for summarization. See [LLM Commits](https://worktrunk.dev/llm-commits/#branch-summaries-experimental) for details.
+Disabled by default — when enabled, each branch's diff is sent to the configured LLM for summarization. See [LLM Commits](https://worktrunk.dev/llm-commits/#branch-summaries) for details.
## JSON API
diff --git a/skills/worktrunk/reference/worktrunk.md b/skills/worktrunk/reference/worktrunk.md
index afa747ac4..cfbf34ddb 100644
--- a/skills/worktrunk/reference/worktrunk.md
+++ b/skills/worktrunk/reference/worktrunk.md
@@ -73,7 +73,7 @@ git branch -d feat{% end %}</td>
- **[Merge workflow](https://worktrunk.dev/merge/)** — squash, rebase, merge, clean up in one command
- **[Interactive picker](https://worktrunk.dev/switch/#interactive-picker)** — browse worktrees with live diff and log previews
- **[Copy build caches](https://worktrunk.dev/step/)** — skip cold starts by sharing `target/`, `node_modules/`, etc between worktrees
-- **[`wt list --full`](https://worktrunk.dev/list/#full-mode)** — [CI status](https://worktrunk.dev/list/#ci-status) and [AI-generated summaries](https://worktrunk.dev/list/#llm-summaries-experimental) per branch
+- **[`wt list --full`](https://worktrunk.dev/list/#full-mode)** — [CI status](https://worktrunk.dev/list/#ci-status) and [AI-generated summaries](https://worktrunk.dev/list/#llm-summaries) per branch
- **[PR checkout](https://worktrunk.dev/switch/#github-pull-requests)** — `wt switch pr:123` to jump straight to a PR's branch
- **[Dev server per worktree](https://worktrunk.dev/hook/#dev-servers)** — `hash_port` template filter gives each worktree a unique port
- ...and **[lots more](#next-steps)**
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 9d5be95d9..130e75604 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -478,7 +478,7 @@ The table renders progressively: branch names, paths, and commit hashes appear i
## Full mode
-`--full` adds columns that require network access or LLM calls: [CI status](#ci-status) (GitHub/GitLab pipeline pass/fail), line diffs since the merge-base, and [LLM-generated summaries](#llm-summaries-experimental) of each branch's changes. The table displays instantly and columns fill in as results arrive.
+`--full` adds columns that require network access or LLM calls: [CI status](#ci-status) (GitHub/GitLab pipeline pass/fail), line diffs since the merge-base, and [LLM-generated summaries](#llm-summaries) of each branch's changes. The table displays instantly and columns fill in as results arrive.
## Examples
@@ -1251,7 +1251,7 @@ build = "cargo build --release"
## User hooks
-Define hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval. For repository-specific user hooks, see [setting overrides](@/config.md#setting-overrides-experimental).
+Define hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval. For repository-specific user hooks, see [setting overrides](@/config.md#setting-overrides).
```toml
# ~/.config/worktrunk/config.toml
diff --git a/src/help.rs b/src/help.rs
index 96e35202a..0646af53e 100644
--- a/src/help.rs
+++ b/src/help.rs
@@ -425,7 +425,7 @@ Commands with pages: merge, switch, remove, list"
/// | CLI source | Web docs |
/// |------------|----------|
/// | `` `●` green `` | `<span style='color:#0a0'>●</span> green` |
-/// | `[experimental]` | `<span class="badge-experimental">experimental</span>` |
+/// | `[experimental]` | `<span class="badge-experimental"></span>` (text via CSS) |
/// | plain URL | markdown link |
///
/// Only runs on `after_long_help` markdown — not on terminal reference blocks (those go
@@ -441,10 +441,11 @@ fn post_process_for_html(text: &str) -> String {
.replace("`●` yellow", "<span style='color:#a60'>●</span> yellow")
.replace("`⚠` yellow", "<span style='color:#a60'>⚠</span> yellow")
.replace("`●` gray", "<span style='color:#888'>●</span> gray")
- // Experimental badges — styled pill labels for web docs
+ // Experimental badges — empty span, text added via CSS ::after.
+ // Empty so the span doesn't affect Zola's heading slug generation.
.replace(
"[experimental]",
- "<span class=\"badge-experimental\">experimental</span>",
+ "<span class=\"badge-experimental\"></span>",
)
// Convert plain URL references to markdown links for web docs
// CLI shows: "Open an issue at https://github.com/max-sixty/worktrunk."
@@ -572,6 +573,18 @@ 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(),
+ )
+ } else {
+ ("", raw_help)
+ };
+
// Split content at first subdoc placeholder so command reference comes before nested subdocs
let subdoc_marker = "<!-- subdoc:";
let (main_content, subdoc_content) = if let Some(pos) = raw_help.find(subdoc_marker) {
@@ -598,7 +611,7 @@ fn format_subcommand_section(
let reference_block = get_help_reference(&command_path, Some(80));
// Format the section: heading, main content, command reference, then nested subdocs
- let mut section = format!("## {}\n\n", full_command);
+ let mut section = format!("## {full_command}{heading_badge}\n\n");
if !main_help.is_empty() {
section.push_str(main_help.trim());
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index 258318b30..15b3a18b4 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -1585,7 +1585,7 @@ fn transform_docs_for_skill(content: &str) -> String {
// Replace experimental markers (shortcode and HTML badge) with plain text
let content = ZOLA_EXPERIMENTAL_SHORTCODE.replace_all(&content, "[experimental]");
let content = content.replace(
- "<span class=\"badge-experimental\">experimental</span>",
+ "<span class=\"badge-experimental\"></span>",
"[experimental]",
);