Skip to content

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

feat(docs): style experimental markers as badge pills (#1499)

Maximilian Roos0760817af72b
diff --git a/dev/config.example.toml b/dev/config.example.toml
index 95560cc49..f1dfbe64f 100644
--- a/dev/config.example.toml
+++ b/dev/config.example.toml
@@ -105,7 +105,7 @@
#
# 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. 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/config.md b/docs/content/config.md
index ac32034ef..06eb6095b 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -187,7 +187,7 @@ For context:
Entries are keyed by project identifier (e.g., `github.com/user/repo`).
-#### Setting overrides (Experimental)
+#### Setting overrides <span class="badge-experimental">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 d4e281b57..f11799a8e 100644
--- a/docs/content/faq.md
+++ b/docs/content/faq.md
@@ -98,7 +98,7 @@ Created by `wt config shell install`:
- **Bash**: adds line to `~/.bashrc`
- **Zsh**: adds line to `~/.zshrc` (or `$ZDOTDIR/.zshrc`)
- **Fish**: creates `~/.config/fish/functions/wt.fish` and `~/.config/fish/completions/wt.fish`
-- **Nushell** (experimental): creates `$nu.default-config-dir/vendor/autoload/wt.nu` (typically `~/.config/nushell` on Linux, `~/Library/Application Support/nushell` on macOS)
+- **Nushell** {{ experimental() }}: creates `$nu.default-config-dir/vendor/autoload/wt.nu` (typically `~/.config/nushell` on Linux, `~/Library/Application Support/nushell` on macOS)
- **PowerShell** (Windows): creates both profile files if they don't exist:
- `Documents/PowerShell/Microsoft.PowerShell_profile.ps1` (PowerShell 7+)
- `Documents/WindowsPowerShell/Microsoft.PowerShell_profile.ps1` (Windows PowerShell 5.1)
diff --git a/docs/content/list.md b/docs/content/list.md
index 1a1fdf0da..6f5eb130d 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -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)) (experimental) |
+| Summary | LLM-generated branch summary (`--full` + `summary = true`, requires [`commit.generation`](@/config.md#commit)) <span class="badge-experimental">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 (experimental)
+### LLM summaries <span class="badge-experimental">experimental</span>
Reuses the [`commit.generation`](@/config.md#commit) command — the same LLM that generates commit messages. Enable with `summary = true` in `[list]` config. Results are cached until the branch's diff changes.
diff --git a/docs/content/llm-commits.md b/docs/content/llm-commits.md
index 635b74551..02ec1aa27 100644
--- a/docs/content/llm-commits.md
+++ b/docs/content/llm-commits.md
@@ -89,7 +89,7 @@ $ wt step squash
See [`wt merge`](@/merge.md) and [`wt step`](@/step.md) for full documentation.
-## Branch summaries (experimental)
+## Branch summaries <span class="badge-experimental">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 b5c8653bb..53f63a506 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) — [experimental] Run a command in every worktree
-- [`promote`](#wt-step-promote) — [experimental] Swap a branch into the main worktree
+- [`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
- [`prune`](#wt-step-prune) — Remove worktrees and branches merged into the default branch
-- [`relocate`](#wt-step-relocate) — [experimental] Move worktrees to expected paths
-- [`<alias>`](#aliases) — [experimental] Run a configured command alias
+- [`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
## See also
@@ -453,7 +453,7 @@ Usage: <b><span class=c>wt step copy-ignored</span></b> <span class=c>[OPTIONS]<
## wt step for-each
-[experimental] Run command in each worktree. Executes sequentially with real-time output; continues on failure.
+<span class="badge-experimental">experimental</span> 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.
@@ -521,7 +521,7 @@ Usage: <b><span class=c>wt step for-each</span></b> <span class=c>[OPTIONS]</spa
## wt step promote
-[experimental] Swap a branch into the main worktree. Exchanges branches and gitignored files between two worktrees.
+<span class="badge-experimental">experimental</span> 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.
@@ -595,7 +595,7 @@ Usage: <b><span class=c>wt step promote</span></b> <span class=c>[OPTIONS]</span
## wt step prune
-[experimental] Remove worktrees merged into the default branch.
+<span class="badge-experimental">experimental</span> 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.
@@ -665,7 +665,7 @@ Usage: <b><span class=c>wt step prune</span></b> <span class=c>[OPTIONS]</span>
## wt step relocate
-[experimental] Move worktrees to expected paths. Relocates worktrees whose path doesn't match the worktree-path template.
+<span class="badge-experimental">experimental</span> 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/sass/custom.scss b/docs/sass/custom.scss
index 8998536a2..dc499e8b6 100644
--- a/docs/sass/custom.scss
+++ b/docs/sass/custom.scss
@@ -989,6 +989,27 @@ ul > li::marker {
color: var(--wt-color-accent);
}
+// ============================================================================
+// Badges — status labels (experimental, deprecated, etc.)
+// ============================================================================
+
+// Experimental badge — quiet label, reads as metadata not emphasis
+.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;
+
+}
+
// ============================================================================
// Figures
// ============================================================================
diff --git a/docs/templates/shortcodes/experimental.html b/docs/templates/shortcodes/experimental.html
new file mode 100644
index 000000000..44bfd92b5
--- /dev/null
+++ b/docs/templates/shortcodes/experimental.html
@@ -0,0 +1 @@
+<span class="badge-experimental">experimental</span>
diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.md
index 018fda14f..dad87de3d 100644
--- a/skills/worktrunk/reference/config.md
+++ b/skills/worktrunk/reference/config.md
@@ -178,7 +178,7 @@ 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. Hooks append — both global and per-project hooks run. Aliases merge — per-project aliases override global aliases on name collision.
diff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.md
index 65dcbf93e..a6b953ae4 100644
--- a/skills/worktrunk/reference/faq.md
+++ b/skills/worktrunk/reference/faq.md
@@ -91,7 +91,7 @@ Created by `wt config shell install`:
- **Bash**: adds line to `~/.bashrc`
- **Zsh**: adds line to `~/.zshrc` (or `$ZDOTDIR/.zshrc`)
- **Fish**: creates `~/.config/fish/functions/wt.fish` and `~/.config/fish/completions/wt.fish`
-- **Nushell** (experimental): creates `$nu.default-config-dir/vendor/autoload/wt.nu` (typically `~/.config/nushell` on Linux, `~/Library/Application Support/nushell` on macOS)
+- **Nushell** [experimental]: creates `$nu.default-config-dir/vendor/autoload/wt.nu` (typically `~/.config/nushell` on Linux, `~/Library/Application Support/nushell` on macOS)
- **PowerShell** (Windows): creates both profile files if they don't exist:
- `Documents/PowerShell/Microsoft.PowerShell_profile.ps1` (PowerShell 7+)
- `Documents/WindowsPowerShell/Microsoft.PowerShell_profile.ps1` (Windows PowerShell 5.1)
diff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.md
index 6842cfb64..5d44f40af 100644
--- a/skills/worktrunk/reference/list.md
+++ b/skills/worktrunk/reference/list.md
@@ -62,7 +62,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`](https://worktrunk.dev/config/#commit)) (experimental) |
+| Summary | LLM-generated branch summary (`--full` + `summary = true`, requires [`commit.generation`](https://worktrunk.dev/config/#commit)) [experimental] |
| Remote⇅ | Commits ahead/behind tracking branch |
| CI | Pipeline status (`--full`) |
| Path | Worktree directory |
@@ -89,7 +89,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 (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. 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 483954d9b..f1c17c2aa 100644
--- a/skills/worktrunk/reference/llm-commits.md
+++ b/skills/worktrunk/reference/llm-commits.md
@@ -75,7 +75,7 @@ $ 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/src/cli/config.rs b/src/cli/config.rs
index 849ae559b..842f4c1c7 100644
--- a/src/cli/config.rs
+++ b/src/cli/config.rs
@@ -27,7 +27,7 @@ Zsh (~/.zshrc):
eval "$(wt config shell init zsh)"
```
-Nushell (experimental) — save to vendor autoload directory:
+Nushell [experimental] — save to vendor autoload directory:
```console
wt config shell init nu | save -f ($nu.default-config-dir | path join vendor/autoload/wt.nu)
```"#
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 3b81cf149..85a59b36c 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -518,7 +518,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)) (experimental) |
+| Summary | LLM-generated branch summary (`--full` + `summary = true`, requires [`commit.generation`](@/config.md#commit)) [experimental] |
| Remote⇅ | Commits ahead/behind tracking branch |
| CI | Pipeline status (`--full`) |
| Path | Worktree directory |
@@ -545,7 +545,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 (experimental)
+### LLM summaries [experimental]
Reuses the [`commit.generation`](@/config.md#commit) command — the same LLM that generates commit messages. Enable with `summary = true` in `[list]` config. Results are cached until the branch's diff changes.
@@ -1709,7 +1709,7 @@ 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. Hooks append — both global and per-project hooks run. Aliases merge — per-project aliases override global aliases on name collision.
diff --git a/src/help.rs b/src/help.rs
index e76734446..96e35202a 100644
--- a/src/help.rs
+++ b/src/help.rs
@@ -4,6 +4,42 @@
//! - Pager support for `--help` output (git-style)
//! - Markdown rendering for help text
//! - Web documentation generation via `--help-page` and `--help-md`
+//!
+//! # Web docs generation (`--help-page`)
+//!
+//! Each command page flows through several transforms before becoming web docs:
+//!
+//! ```text
+//! cli.rs (source of truth)
+//! ├── after_long_help: markdown prose with [experimental] markers, `●` dots, plain URLs
+//! └── doc comments (/// lines): definition + subtitle for lead paragraph
+//! │
+//! ▼
+//! combine_command_docs() — assembles "definition. subtitle\n\n<after_long_help>"
+//! │
+//! ▼
+//! post_process_for_html() — text replacements on after_long_help markdown:
+//! │ [experimental] → badge <span>
+//! │ `●` green → colored <span>
+//! │ plain URLs → markdown links
+//! ▼
+//! --help-page stdout — markdown with embedded HTML spans
+//! │
+//! ▼ (readme_sync.rs test captures and writes to docs/)
+//! │
+//! convert_command_reference_to_html() — backtick-fenced --help blocks → {% terminal() %}
+//! expand_command_placeholders() — ```bash wt list``` → snapshot terminal blocks
+//! │
+//! ▼
+//! docs/content/{command}.md — final markdown consumed by Zola
+//! ```
+//!
+//! **Manually-written pages** (faq.md, llm-commits.md) bypass this pipeline.
+//! They use `{{ experimental() }}` (Zola shortcode) for badges.
+//!
+//! **Skill reference files** mirror docs/ content via `transform_docs_for_skill()`,
+//! which strips Zola syntax (terminal shortcodes, `{{ experimental() }}` → `[experimental]`)
+//! for plain-markdown consumption.
use std::process;
@@ -341,7 +377,7 @@ Commands with pages: merge, switch, remove, list"
// Process main content (before subdocs)
let main_help = {
let text = expand_demo_placeholders(main_content);
- colorize_ci_status_for_html(&text)
+ post_process_for_html(&text)
};
// Get the help reference block (wrap at 80 chars for web docs, with colors for HTML)
@@ -366,28 +402,37 @@ Commands with pages: merge, switch, remove, list"
std::println!();
std::println!("```");
- // Subdocs follow, each with their own command reference at the end
+ // Subdocs follow, each with their own command reference at the end.
+ // post_process_for_html is already applied inside format_subcommand_section,
+ // so we don't apply it again here (it would corrupt HTML inside reference blocks).
if let Some(subdocs) = subdoc_content {
let subdocs_expanded = expand_subdoc_placeholders(subdocs, sub, &parent_name);
- let subdocs_processed = colorize_ci_status_for_html(&subdocs_expanded);
std::println!();
std::println!("# Subcommands");
std::println!();
- std::println!("{}", subdocs_processed.trim());
+ std::println!("{}", subdocs_expanded.trim());
}
std::println!();
std::println!("<!-- END AUTO-GENERATED from `wt {subcommand} --help-page` -->");
}
-/// Add HTML color spans for CI status dots in help page output.
+/// Post-process CLI help content for web docs rendering.
///
-/// Transforms plain text like "`●` green" into colored HTML spans for web rendering.
-/// This is the web-docs counterpart to md_help::colorize_status_symbols() which
-/// produces ANSI codes for terminal output.
+/// Applies text replacements to `after_long_help` content before it becomes markdown
+/// in the docs site. Each replacement converts a CLI-friendly marker into styled HTML:
///
-/// Also converts plain URL references to markdown links for web docs.
-fn colorize_ci_status_for_html(text: &str) -> String {
+/// | CLI source | Web docs |
+/// |------------|----------|
+/// | `` `●` green `` | `<span style='color:#0a0'>●</span> green` |
+/// | `[experimental]` | `<span class="badge-experimental">experimental</span>` |
+/// | plain URL | markdown link |
+///
+/// Only runs on `after_long_help` markdown — not on terminal reference blocks (those go
+/// through ANSI-to-HTML via `convert_command_reference_to_html` in readme_sync.rs).
+///
+/// The terminal counterpart is `md_help::colorize_status_symbols()`.
+fn post_process_for_html(text: &str) -> String {
text
// CI status colors (in table cells)
.replace("`●` green", "<span style='color:#0a0'>●</span> green")
@@ -396,6 +441,11 @@ fn colorize_ci_status_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
+ .replace(
+ "[experimental]",
+ "<span class=\"badge-experimental\">experimental</span>",
+ )
// Convert plain URL references to markdown links for web docs
// CLI shows: "Open an issue at https://github.com/max-sixty/worktrunk."
// Web shows: "[Open an issue](https://github.com/max-sixty/worktrunk/issues)."
@@ -533,7 +583,7 @@ fn format_subcommand_section(
// Process main content (before any nested subdocs)
let main_help = {
let text = increase_heading_levels(main_content);
- colorize_ci_status_for_html(&text)
+ post_process_for_html(&text)
};
// Build command path from parent_name: "wt config" -> ["config", "create"]
@@ -560,12 +610,13 @@ fn format_subcommand_section(
section.push_str(reference_block.trim());
section.push_str("\n```\n");
- // Expand nested subdocs after the command reference
+ // Expand nested subdocs after the command reference.
+ // post_process_for_html is already applied inside format_subcommand_section,
+ // so we don't apply it again here (it would corrupt HTML inside reference blocks).
if let Some(subdocs) = subdoc_content {
let subdocs_expanded = expand_subdoc_placeholders(subdocs, sub, &full_command);
- let subdocs_processed = colorize_ci_status_for_html(&subdocs_expanded);
section.push('\n');
- section.push_str(subdocs_processed.trim());
+ section.push_str(subdocs_expanded.trim());
section.push('\n');
}
diff --git a/src/md_help.rs b/src/md_help.rs
index 72bc4b73a..ed6fbcb89 100644
--- a/src/md_help.rs
+++ b/src/md_help.rs
@@ -252,7 +252,7 @@ fn unescape_table_pipes(line: &str) -> String {
/// restructuring since `cmd` is consumed by `try_get_matches_from_mut`.
///
/// Current workaround: Use plain URLs in cli.rs (terminals auto-link `https://...`),
-/// transform to markdown links for web docs in `colorize_ci_status_for_html()`.
+/// transform to markdown links for web docs in `post_process_for_html()`.
fn strip_markdown_links(line: &str) -> String {
let mut result = String::new();
let mut chars = line.chars().peekable();
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index 4f022b9bb..258318b30 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -1538,6 +1538,10 @@ static ZOLA_TITLE_PATTERN: LazyLock<Regex> =
static ZOLA_TERMINAL_PATTERN: LazyLock<Regex> =
LazyLock::new(|| Regex::new(r"(?s)\{% terminal\(\) %\}\n?(.*?)\{% end %\}").unwrap());
+/// Regex to replace Zola experimental shortcode with plain text for skill files
+static ZOLA_EXPERIMENTAL_SHORTCODE: LazyLock<Regex> =
+ LazyLock::new(|| Regex::new(r"\{\{\s*experimental\(\)\s*\}\}").unwrap());
+
/// Regex to strip AUTO-GENERATED marker comments (just the comments, not content)
static AUTO_GENERATED_MARKER_PATTERN: LazyLock<Regex> = LazyLock::new(|| {
Regex::new(r"<!-- ⚠️ AUTO-GENERATED[^>]*-->\n*|<!-- END AUTO-GENERATED[^>]*-->\n*").unwrap()
@@ -1554,6 +1558,7 @@ static HTML_FIGURE_PATTERN: LazyLock<Regex> =
/// - Strips Zola terminal shortcodes ({% terminal() %}...{% end %}) - keeps inner content
/// - Strips AUTO-GENERATED marker comments (keeps content)
/// - Strips HTML figure elements (demo GIFs not useful for skill)
+/// - Replaces Zola shortcodes with plain text equivalents
/// - Converts Zola internal links (@/page.md) -> full URLs
/// - Removes "See also" section (just links to other docs pages)
fn transform_docs_for_skill(content: &str) -> String {
@@ -1577,6 +1582,13 @@ fn transform_docs_for_skill(content: &str) -> String {
// Strip HTML figure elements (demo GIFs)
let content = HTML_FIGURE_PATTERN.replace_all(&content, "");
+ // 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>",
+ "[experimental]",
+ );
+
// Transform Zola internal links to full URLs
let content = ZOLA_LINK_PATTERN
.replace_all(&content, |caps: &regex::Captures| {
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
index 2a6d2b04c..9ef91b88d 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -164,7 +164,7 @@ Creates ~/.config/worktrunk/config.toml with the following content:
  #
  # 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. Hooks append — both global and per-project hooks run. Aliases merge — per-project aliases override global aliases on name collision.
  #
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index 383981d57..8a4e5601c 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -209,7 +209,7 @@ 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. Hooks append — both global and per-project hooks run. Aliases merge — per-project aliases override global aliases on name collision.
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
index 820e94e90..297aba1e6 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
@@ -107,7 +107,7 @@ Output as JSON for scripting:
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) (experimental)
+ Summary LLM-generated branch summary (--full + summary = true, requires commit.generation) [experimental]
Remote⇅ Commits ahead/behind tracking branch
CI Pipeline status (--full)
Path Worktree directory
@@ -134,7 +134,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 (experimental)
+LLM summaries [experimental]
Reuses the commit.generation command — the same LLM that generates commit messages. Enable with summary = true in [list] config. Results are cached until the branch's diff changes.
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
index 3ceaef124..7fba636a2 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
@@ -116,7 +116,7 @@ Output as JSON for scripting:
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) (experimental)
+ commit.generation) [experimental]
Remote⇅ Commits ahead/behind tracking branch
CI Pipeline status (--full)
Path Worktree directory
@@ -149,7 +149,7 @@ 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 command — the same LLM that generates commit
messages. Enable with summary = true in [list] config. Results are cached until