Skip to content

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

feat(docs): include long_about subtitles in web docs (#624)

Maximilian Rooscfc8a671a3f3
diff --git a/.claude-plugin/skills/worktrunk/reference/merge.md b/.claude-plugin/skills/worktrunk/reference/merge.md
index c921a3205..dfdccac5f 100644
--- a/.claude-plugin/skills/worktrunk/reference/merge.md
+++ b/.claude-plugin/skills/worktrunk/reference/merge.md
@@ -1,5 +1,7 @@
# wt merge
+Squash & rebase, fast-forward target, remove the worktree.
+
Merge the current branch into the target branch, defaulting to the main branch. Unlike `git merge`, this merges the current branch into a target (rather than a target into the current branch). Similar to clicking "Merge pull request" on GitHub.
## Examples
diff --git a/.claude-plugin/skills/worktrunk/reference/select.md b/.claude-plugin/skills/worktrunk/reference/select.md
index 525140c99..356099b68 100644
--- a/.claude-plugin/skills/worktrunk/reference/select.md
+++ b/.claude-plugin/skills/worktrunk/reference/select.md
@@ -1,5 +1,7 @@
# wt select
+Browse and switch worktrees with live preview.
+
Interactive worktree picker with live preview. Navigate worktrees with keyboard shortcuts and press Enter to switch.
## Examples
diff --git a/.claude-plugin/skills/worktrunk/reference/switch.md b/.claude-plugin/skills/worktrunk/reference/switch.md
index 3a69f1029..c0b4230eb 100644
--- a/.claude-plugin/skills/worktrunk/reference/switch.md
+++ b/.claude-plugin/skills/worktrunk/reference/switch.md
@@ -1,5 +1,7 @@
# wt switch
+Change directory to a worktree, creating one if needed.
+
Worktrees are addressed by branch name; paths are computed from a configurable template. Unlike `git switch`, this navigates between worktrees rather than changing branches in place.
## Examples
diff --git a/docs/content/merge.md b/docs/content/merge.md
index 186be448e..5809c920f 100644
--- a/docs/content/merge.md
+++ b/docs/content/merge.md
@@ -8,6 +8,8 @@ group = "Commands"
<!-- ⚠️ AUTO-GENERATED from `wt merge --help-page` — edit cli.rs to update -->
+Squash & rebase, fast-forward target, remove the worktree.
+
Merge the current branch into the target branch, defaulting to the main branch. Unlike `git merge`, this merges the current branch into a target (rather than a target into the current branch). Similar to clicking "Merge pull request" on GitHub.
<figure class="demo">
diff --git a/docs/content/select.md b/docs/content/select.md
index c9126821a..94c73511a 100644
--- a/docs/content/select.md
+++ b/docs/content/select.md
@@ -8,6 +8,8 @@ group = "Commands"
<!-- ⚠️ AUTO-GENERATED from `wt select --help-page` — edit cli.rs to update -->
+Browse and switch worktrees with live preview.
+
Interactive worktree picker with live preview. Navigate worktrees with keyboard shortcuts and press Enter to switch.
<figure class="demo">
diff --git a/docs/content/switch.md b/docs/content/switch.md
index e2e7b5cf5..ed6e7c3cf 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -8,6 +8,10 @@ group = "Commands"
<!-- ⚠️ AUTO-GENERATED from `wt switch --help-page` — edit cli.rs to update -->
+Change directory to a worktree, creating one if needed.
+
+Worktrees are addressed by branch name; paths are computed from a configurable template. Unlike `git switch`, this navigates between worktrees rather than changing branches in place.
+
<figure class="demo">
<picture>
<source srcset="/assets/docs/dark/wt-switch.gif" media="(prefers-color-scheme: dark)">
@@ -15,8 +19,6 @@ group = "Commands"
</picture>
</figure>
-Worktrees are addressed by branch name; paths are computed from a configurable template. Unlike `git switch`, this navigates between worktrees rather than changing branches in place.
-
## Examples
```bash
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index c927df286..95ae3ca4a 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -245,9 +245,9 @@ pub(crate) enum Commands {
/// Switch to a worktree
///
/// Change directory to a worktree, creating one if needed.
- #[command(after_long_help = r#"<!-- demo: wt-switch.gif 1600x900 -->
-
-Worktrees are addressed by branch name; paths are computed from a configurable template. Unlike `git switch`, this navigates between worktrees rather than changing branches in place.
+ #[command(
+ after_long_help = r#"Worktrees are addressed by branch name; paths are computed from a configurable template. Unlike `git switch`, this navigates between worktrees rather than changing branches in place.
+<!-- demo: wt-switch.gif 1600x900 -->
## Examples
@@ -308,7 +308,8 @@ To change which branch a worktree is on, use `git switch` inside that worktree.
- [`wt list`](@/list.md) — View all worktrees
- [`wt remove`](@/remove.md) — Delete worktrees when done
- [`wt merge`](@/merge.md) — Integrate changes back to the default branch
-"#)]
+"#
+ )]
Switch {
/// Branch name
///
diff --git a/src/help.rs b/src/help.rs
index aabdea5b9..a60cc4849 100644
--- a/src/help.rs
+++ b/src/help.rs
@@ -248,15 +248,38 @@ fn handle_help_page(args: &[String]) {
return;
};
- // Get the after_long_help content
+ // Get the long_about (subtitle) and after_long_help content
// Transform for web docs: console→bash, status colors, demo images
// Subdocs are expanded separately so main Command reference comes first
let parent_name = format!("wt {}", subcommand);
- let raw_help = sub
+ let about = sub.get_about().map(|s| s.to_string());
+ let long_about = sub.get_long_about().map(|s| s.to_string());
+ let after_long_help = sub
.get_after_long_help()
.map(|s| s.to_string())
.unwrap_or_default();
+ // Extract subtitle: the part of long_about beyond the short about
+ // Doc comments produce: "Short about\n\nLong description" in long_about
+ // We only want the long description part (subtitle) for web docs
+ let subtitle = match (&about, &long_about) {
+ (Some(short), Some(long)) if long.starts_with(short) => {
+ let rest = long[short.len()..].trim_start();
+ if rest.is_empty() {
+ None
+ } else {
+ Some(rest.to_string())
+ }
+ }
+ _ => None,
+ };
+
+ // Combine: subtitle followed by after_long_help (conceptual docs)
+ let raw_help = match subtitle {
+ Some(sub) => format!("{sub}\n\n{after_long_help}"),
+ None => after_long_help,
+ };
+
// Split content at first subdoc placeholder
let subdoc_marker = "<!-- subdoc:";
let (main_content, subdoc_content) = if let Some(pos) = raw_help.find(subdoc_marker) {
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
index d07960b56..14ad9bbdc 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -84,7 +84,6 @@ Usage: wt switch [OPTIONS] <BRANCH> [--
-v, --verbose...
Show debug info (-v), or also write diagnostic report (-vv)
-
Worktrees are addressed by branch name; paths are computed from a configurable template. Unlike git switch, this navigates between worktrees rather than changing branches in place.
Examples