Skip to content

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.md
index 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.md
index 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.md
index 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 `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 [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 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 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.html
index 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.html
index 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.xml
new file mode 100644
index 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.md
index 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 `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 [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 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/src/help.rs b/src/help.rs
index 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 empty
fn 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.rs
index 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` instead
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index 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: &regex::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(&current, &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(&current) {
- let before = &current[..m.start()];
- let after = &current[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!(