Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Add page metadata, canonical URLs, and structured data to docs (#1167)
Maximilian Roos1cf2c8203f2b
diff --git a/docs/content/claude-code.md b/docs/content/claude-code.mdindex 8405fbf4d..e328c69a4 100644--- a/docs/content/claude-code.md+++ b/docs/content/claude-code.md@@ -1,5 +1,6 @@+++title = "Claude Code Integration"+description = "Worktrunk plugin for Claude Code: configuration skill for setup help and activity tracking for wt list."weight = 23[extra]diff --git a/docs/content/config.md b/docs/content/config.mdindex c6bb768ca..fa75e9af2 100644--- a/docs/content/config.md+++ b/docs/content/config.md@@ -1,5 +1,6 @@+++title = "wt config"+description = "Manage user & project configs. Includes shell integration, hooks, and saved state."weight = 15[extra]diff --git a/docs/content/faq.md b/docs/content/faq.mdindex 2f69e203a..d4e281b57 100644--- a/docs/content/faq.md+++ b/docs/content/faq.md@@ -1,5 +1,6 @@+++title = "FAQ"+description = "Common questions about Worktrunk: comparison to git worktree and branch switching, bare repos, TUI support, and more."weight = 25[extra]@@ -165,7 +166,7 @@ Worktrunk runs `git` commands internally and optionally runs `gh` (GitHub) or `g1. **User hooks** (`~/.config/worktrunk/config.toml`) — Personal automation for all repositories2. **Project hooks** (`.config/wt.toml`) — Repository-specific automation-3. **LLM commands** (`~/.config/worktrunk/config.toml`) — Commit message generation and [picker summaries](@/llm-commits.md#picker-summaries)+3. **LLM commands** (`~/.config/worktrunk/config.toml`) — Commit message generation and [branch summaries](@/llm-commits.md#branch-summaries-experimental)4. **--execute flag** — Explicitly provided commandsUser 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.mdindex beb915bb1..ddf83741c 100644--- a/docs/content/hook.md+++ b/docs/content/hook.md@@ -1,5 +1,6 @@+++title = "wt hook"+description = "Run configured hooks."weight = 17[extra]diff --git a/docs/content/list.md b/docs/content/list.mdindex 9f3bcb86e..38aa7254b 100644--- a/docs/content/list.md+++ b/docs/content/list.md@@ -1,5 +1,6 @@+++title = "wt list"+description = "List worktrees and their status."weight = 11[extra]diff --git a/docs/content/llm-commits.md b/docs/content/llm-commits.mdindex c5ed5b12b..480d22091 100644--- a/docs/content/llm-commits.md+++ b/docs/content/llm-commits.md@@ -1,5 +1,6 @@+++title = "LLM Commit Messages"+description = "Generate commit messages from diffs using any LLM. Integrates with wt merge, wt step commit, and wt step squash."weight = 22[extra]diff --git a/docs/content/merge.md b/docs/content/merge.mdindex c09099d06..7ed41a4b4 100644--- a/docs/content/merge.md+++ b/docs/content/merge.md@@ -1,5 +1,6 @@+++title = "wt merge"+description = "Merge current branch into target. Squash & rebase, fast-forward target, remove the worktree."weight = 13[extra]diff --git a/docs/content/remove.md b/docs/content/remove.mdindex e026a1d97..547e4bf63 100644--- a/docs/content/remove.md+++ b/docs/content/remove.md@@ -1,5 +1,6 @@+++title = "wt remove"+description = "Remove worktree; delete branch if merged. Defaults to the current worktree."weight = 12[extra]diff --git a/docs/content/step.md b/docs/content/step.mdindex 874410604..fe29c3eb3 100644--- a/docs/content/step.md+++ b/docs/content/step.md@@ -1,5 +1,6 @@+++title = "wt step"+description = "Run individual operations. The building blocks of wt merge — commit, squash, rebase, push — plus standalone utilities."weight = 16[extra]diff --git a/docs/content/switch.md b/docs/content/switch.mdindex c2010fd41..82cf59ae3 100644--- a/docs/content/switch.md+++ b/docs/content/switch.md@@ -1,5 +1,6 @@+++title = "wt switch"+description = "Switch to a worktree; create if needed."weight = 10[extra]diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.mdindex db0297528..3e3464701 100644--- a/docs/content/tips-patterns.md+++ b/docs/content/tips-patterns.md@@ -1,5 +1,6 @@+++title = "Tips & Patterns"+description = "Practical recipes for Worktrunk workflows: aliases, shell integration, Zellij layouts, and parallel agent patterns."weight = 24[extra]diff --git a/docs/content/worktrunk.md b/docs/content/worktrunk.mdindex f06bc2971..ee71dd6d4 100644--- a/docs/content/worktrunk.md+++ b/docs/content/worktrunk.md@@ -1,5 +1,6 @@+++title = "Worktrunk"+description = "Git worktree management for parallel AI agents. Core commands, install guide, and quick start."weight = 1+++diff --git a/docs/templates/base.html b/docs/templates/base.htmlindex eec53cd88..089bb6dcb 100644--- a/docs/templates/base.html+++ b/docs/templates/base.html@@ -74,13 +74,15 @@})();</script><meta name="view-transition" content="same-origin">- <meta name="description" content="{{ config.extra.site_description }}">+ {% set page_description = page.description | default(value=config.extra.site_description) %}+ <meta name="description" content="{{ page_description }}">+ <link rel="canonical" href="{{ current_url | default(value=config.base_url) }}"><!-- OpenGraph --><meta property="og:type" content="website"><meta property="og:url" content="{{ current_url | default(value=config.base_url) }}"><meta property="og:title" content="{% if page.title %}{{ page.title }} | {{ config.title }}{% else %}{{ config.title }}{% endif %}">- <meta property="og:description" content="{{ config.extra.site_description }}">+ <meta property="og:description" content="{{ page_description }}"><meta property="og:image" content="{{ config.base_url }}assets/social/social-card.png"><meta property="og:image:width" content="1200"><meta property="og:image:height" content="630">@@ -88,9 +90,40 @@<!-- Twitter Card --><meta name="twitter:card" content="summary_large_image"><meta name="twitter:title" content="{% if page.title %}{{ page.title }} | {{ config.title }}{% else %}{{ config.title }}{% endif %}">- <meta name="twitter:description" content="{{ config.extra.site_description }}">+ <meta name="twitter:description" content="{{ page_description }}"><meta name="twitter:image" content="{{ config.base_url }}assets/social/social-card.png">+ <!-- Structured data -->+ {% if not page.title %}+ <script type="application/ld+json">+ {+ "@context": "https://schema.org",+ "@type": "WebSite",+ "name": "Worktrunk",+ "url": "https://worktrunk.dev/",+ "description": "{{ config.extra.site_description }}"+ }+ </script>+ <script type="application/ld+json">+ {+ "@context": "https://schema.org",+ "@type": "SoftwareApplication",+ "name": "Worktrunk",+ "url": "https://worktrunk.dev/",+ "description": "{{ config.extra.site_description }}",+ "applicationCategory": "DeveloperApplication",+ "operatingSystem": "macOS, Linux, Windows",+ "offers": {+ "@type": "Offer",+ "price": "0",+ "priceCurrency": "USD"+ },+ "codeRepository": "https://github.com/max-sixty/worktrunk",+ "license": "https://opensource.org/licenses/Apache-2.0"+ }+ </script>+ {% endif %}+<!-- Google tag (gtag.js) --><script async src="https://www.googletagmanager.com/gtag/js?id=G-6YY8BDJ4QH"></script><script>diff --git a/docs/templates/index.html b/docs/templates/index.htmlindex 8f53686d6..710f62b08 100644--- a/docs/templates/index.html+++ b/docs/templates/index.html@@ -1,5 +1,7 @@{% extends "base.html" %}+{% block title %}Worktrunk — Git Worktree Manager for AI Agent Workflows{% endblock title %}+{% block hero %}<style>.welcome {diff --git a/docs/templates/sitemap.xml b/docs/templates/sitemap.xmlnew file mode 100644index 000000000..999cda60c--- /dev/null+++ b/docs/templates/sitemap.xml@@ -0,0 +1,13 @@+<?xml version="1.0" encoding="UTF-8"?>+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">+ {%- for sitemap_entry in entries %}+ <url>+ <loc>{{ sitemap_entry.permalink | escape_xml | safe }}</loc>+ {%- if sitemap_entry.updated %}+ <lastmod>{{ sitemap_entry.updated }}</lastmod>+ {%- else %}+ <lastmod>{{ now() | date(format="%Y-%m-%d") }}</lastmod>+ {%- endif %}+ </url>+ {%- endfor %}+</urlset>diff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.mdindex 554ea818c..65dcbf93e 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 `g1. **User hooks** (`~/.config/worktrunk/config.toml`) — Personal automation for all repositories2. **Project hooks** (`.config/wt.toml`) — Repository-specific automation-3. **LLM commands** (`~/.config/worktrunk/config.toml`) — Commit message generation and [picker summaries](https://worktrunk.dev/llm-commits/#picker-summaries)+3. **LLM commands** (`~/.config/worktrunk/config.toml`) — Commit message generation and [branch summaries](https://worktrunk.dev/llm-commits/#branch-summaries-experimental)4. **--execute flag** — Explicitly provided commandsUser 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/src/help.rs b/src/help.rsindex deac7b7d4..eac6740de 100644--- a/src/help.rs+++ b/src/help.rs@@ -40,6 +40,12 @@ pub fn maybe_handle_help_with_pager() -> bool {process::exit(0);}+ // Check for --help-description flag (output meta description for docs)+ if args.iter().any(|a| a == "--help-description") {+ handle_help_description(&args);+ process::exit(0);+ }+// Check for --help-md flag (output raw markdown without ANSI rendering)if args.iter().any(|a| a == "--help-md") {let mut cmd = cli::build_command();@@ -211,6 +217,62 @@ fn strip_ansi_codes(s: &str) -> String {s.ansi_strip().into_owned()}+/// Extract the `about` (definition) and subtitle from a command's metadata.+///+/// The subtitle is the part of `long_about` beyond the short `about`.+/// For `/// Short\n///\n/// Long description`, about = "Short", subtitle = "Long description".+fn extract_about_and_subtitle(cmd: &clap::Command) -> (Option<String>, Option<String>) {+ let about = cmd.get_about().map(|s| s.to_string());+ let long_about = cmd.get_long_about().map(|s| s.to_string());+ 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,+ };+ (about, subtitle)+}++/// Output the meta description for a command's docs page.+///+/// Combines the command's `about` (definition) and `long_about` subtitle into+/// a single description suitable for `<meta name="description">`. This is used+/// by the docs sync test to auto-populate the `description` field in frontmatter.+fn handle_help_description(args: &[String]) {+ let mut cmd = cli::build_command();+ cmd = cmd.color(ColorChoice::Never);++ let subcommand = args+ .iter()+ .filter(|a| *a != "--help-description" && !a.starts_with('-') && !a.ends_with("/wt"))+ .find(|a| !a.contains("target/") && *a != "wt");++ let Some(subcommand) = subcommand else {+ eprintln!("Usage: wt <command> --help-description");+ return;+ };++ let Some(sub) = cmd.find_subcommand(subcommand) else {+ eprintln!("Unknown command: {subcommand}");+ return;+ };++ let (about, subtitle) = extract_about_and_subtitle(sub);++ let description = match (&about, &subtitle) {+ (Some(def), Some(sub)) => format!("{def}. {sub}"),+ (Some(def), None) => format!("{def}."),+ _ => String::new(),+ };++ print!("{description}");+}+/// Generate a full documentation page for a command.////// Output format:@@ -426,28 +488,12 @@ fn expand_subdoc_placeholders(text: &str, parent_cmd: &clap::Command, parent_nam/// - `subtitle` is the extra content in `long_about` beyond the `about`/// - If `long_about` doesn't extend `about`, subtitle is emptyfn combine_command_docs(cmd: &clap::Command) -> String {- let about = cmd.get_about().map(|s| s.to_string());- let long_about = cmd.get_long_about().map(|s| s.to_string());+ let (about, subtitle) = extract_about_and_subtitle(cmd);let after_long_help = cmd.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: definition + subtitle as single lead paragraph, then after_long_help// Definition doesn't have trailing period, subtitle does, so join with ". "match (&about, &subtitle) {diff --git a/tests/integration_tests/help.rs b/tests/integration_tests/help.rsindex 70b5e6b56..230df31b2 100644--- a/tests/integration_tests/help.rs+++ b/tests/integration_tests/help.rs@@ -147,6 +147,54 @@ fn test_help_list_narrow_terminal() {});}+/// Tests --help-description outputs the meta description for docs frontmatter.+#[rstest]+#[case("switch", "Switch to a worktree; create if needed.")]+#[case("merge", "Merge current branch into target. Squash & rebase")]+#[case("hook", "Run configured hooks.")]+fn test_help_description(#[case] cmd: &str, #[case] expected_prefix: &str) {+ let output = wt_command()+ .args([cmd, "--help-description"])+ .output()+ .expect("failed to run wt --help-description");++ assert!(output.status.success());+ let stdout = String::from_utf8_lossy(&output.stdout);+ assert!(+ stdout.starts_with(expected_prefix),+ "Expected description for '{cmd}' to start with '{expected_prefix}', got: {stdout}"+ );+}++#[test]+fn test_help_description_no_subcommand() {+ let output = wt_command()+ .args(["--help-description"])+ .output()+ .expect("failed to run wt --help-description");++ // Exits 0 (eprintln + return, not process::exit(1))+ let stderr = String::from_utf8_lossy(&output.stderr);+ assert!(+ stderr.contains("Usage:"),+ "Expected usage hint, got: {stderr}"+ );+}++#[test]+fn test_help_description_unknown_command() {+ let output = wt_command()+ .args(["nonexistent", "--help-description"])+ .output()+ .expect("failed to run wt --help-description");++ let stderr = String::from_utf8_lossy(&output.stderr);+ assert!(+ stderr.contains("Unknown command"),+ "Expected unknown command error, got: {stderr}"+ );+}+/// Tests that using a nested subcommand at the top level suggests the correct command.////// When users type `wt squash` instead of `wt step squash`, or `wt pre-merge` insteaddiff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rsindex f7309b639..4f022b9bb 100644--- a/tests/integration_tests/readme_sync.rs+++ b/tests/integration_tests/readme_sync.rs@@ -1359,6 +1359,41 @@ fn test_docs_quickstart_examples_are_in_sync() {}}+/// Update or insert the `description` field in TOML frontmatter.+///+/// Handles three cases:+/// - Description field exists → update it+/// - No description field → insert after title line+/// - No frontmatter → return content unchanged+fn sync_frontmatter_description(content: &str, description: &str) -> String {+ static DESC_PATTERN: LazyLock<Regex> =+ LazyLock::new(|| Regex::new(r#"(?m)^description\s*=\s*"[^"]*""#).unwrap());++ let new_field = format!("description = \"{}\"", description.replace('"', "\\\""));++ // Check if we're in a TOML frontmatter block+ if !content.starts_with("+++\n") {+ return content.to_string();+ }++ if DESC_PATTERN.is_match(content) {+ // Replace existing description+ DESC_PATTERN+ .replace(content, new_field.as_str())+ .to_string()+ } else {+ // Insert after title line+ static TITLE_PATTERN: LazyLock<Regex> =+ LazyLock::new(|| Regex::new(r#"(?m)^(title\s*=\s*"[^"]*")\n"#).unwrap());++ TITLE_PATTERN+ .replace(content, |caps: ®ex::Captures| {+ format!("{}\n{}\n", &caps[1], new_field)+ })+ .to_string()+ }+}+/// Command pages generated via `wt <cmd> --help-page`/// Each page preserves its frontmatter and replaces the AUTO-GENERATED marker region./// Note: `select` is excluded because it's a deprecated hidden alias for `wt switch`.@@ -1436,9 +1471,26 @@ fn sync_command_pages(project_root: &Path) -> (Vec<String>, Vec<String>) {}};+ // Get meta description from --help-description+ let desc_output = wt_command()+ .args([cmd, "--help-description"])+ .current_dir(project_root)+ .output()+ .expect("Failed to run wt --help-description");+ let description = String::from_utf8_lossy(&desc_output.stdout)+ .trim()+ .to_string();+let current = fs::read_to_string(&doc_path).unwrap_or_else(|e| panic!("Failed to read {}: {}", doc_path.display(), e));+ // Update frontmatter description field+ let new_content = if !description.is_empty() {+ sync_frontmatter_description(¤t, &description)+ } else {+ current.clone()+ };+// Find the help-page marker region using mirrored END tag// Pattern: <!-- ⚠️ AUTO-GENERATED from `wt cmd --help-page` ... --> ... <!-- END AUTO-GENERATED from `wt cmd --help-page` -->let marker_pattern = Regex::new(&format!(@@ -1446,9 +1498,9 @@ fn sync_command_pages(project_root: &Path) -> (Vec<String>, Vec<String>) {cmd, cmd)).unwrap();- let new_content = if let Some(m) = marker_pattern.find(¤t) {- let before = ¤t[..m.start()];- let after = ¤t[m.end()..];+ let new_content = if let Some(m) = marker_pattern.find(&new_content) {+ let before = &new_content[..m.start()];+ let after = &new_content[m.end()..];format!("{}{}{}", before, generated.trim(), after)} else {errors.push(format!(