Skip to content

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

docs(site): add llms.txt + .md companions (#2404)

Maximilian Roos89dceed12ea0
diff --git a/docs/static/claude-code.md b/docs/static/claude-code.md
new file mode 120000
index 000000000..4ef1a5dcb
--- /dev/null
+++ b/docs/static/claude-code.md
@@ -0,0 +1 @@
+../../skills/worktrunk/reference/claude-code.md
\ No newline at end of file
diff --git a/docs/static/config.md b/docs/static/config.md
new file mode 120000
index 000000000..697a161ab
--- /dev/null
+++ b/docs/static/config.md
@@ -0,0 +1 @@
+../../skills/worktrunk/reference/config.md
\ No newline at end of file
diff --git a/docs/static/extending.md b/docs/static/extending.md
new file mode 120000
index 000000000..bf0f8fe8a
--- /dev/null
+++ b/docs/static/extending.md
@@ -0,0 +1 @@
+../../skills/worktrunk/reference/extending.md
\ No newline at end of file
diff --git a/docs/static/faq.md b/docs/static/faq.md
new file mode 120000
index 000000000..ebdb26221
--- /dev/null
+++ b/docs/static/faq.md
@@ -0,0 +1 @@
+../../skills/worktrunk/reference/faq.md
\ No newline at end of file
diff --git a/docs/static/hook.md b/docs/static/hook.md
new file mode 120000
index 000000000..e1be34c6c
--- /dev/null
+++ b/docs/static/hook.md
@@ -0,0 +1 @@
+../../skills/worktrunk/reference/hook.md
\ No newline at end of file
diff --git a/docs/static/list.md b/docs/static/list.md
new file mode 120000
index 000000000..20d2132b8
--- /dev/null
+++ b/docs/static/list.md
@@ -0,0 +1 @@
+../../skills/worktrunk/reference/list.md
\ No newline at end of file
diff --git a/docs/static/llm-commits.md b/docs/static/llm-commits.md
new file mode 120000
index 000000000..eff709a35
--- /dev/null
+++ b/docs/static/llm-commits.md
@@ -0,0 +1 @@
+../../skills/worktrunk/reference/llm-commits.md
\ No newline at end of file
diff --git a/docs/static/llms.txt b/docs/static/llms.txt
new file mode 100644
index 000000000..1ee5cb58f
--- /dev/null
+++ b/docs/static/llms.txt
@@ -0,0 +1,28 @@
+# Worktrunk
+
+> CLI for Git worktree management, designed for parallel AI agent workflows.
+
+Worktrunk is a CLI for git worktree management, designed for running AI agents
+in parallel.
+
+Worktrunk's three core commands make worktrees as easy as branches.
+Plus, Worktrunk has a bunch of quality-of-life features to simplify working
+with many parallel changes, including hooks to automate local workflows.
+
+## Commands
+
+- [wt switch](https://worktrunk.dev/switch.md): Switch to a worktree; create if needed.
+- [wt list](https://worktrunk.dev/list.md): List worktrees and their status.
+- [wt remove](https://worktrunk.dev/remove.md): Remove worktree; delete branch if merged. Defaults to the current worktree.
+- [wt merge](https://worktrunk.dev/merge.md): Merge current branch into the target branch. Squash & rebase, fast-forward the target branch, remove the worktree.
+- [wt config](https://worktrunk.dev/config.md): Manage user & project configs. Includes shell integration, hooks, and saved state.
+- [wt step](https://worktrunk.dev/step.md): Run individual operations. The building blocks of wt merge — commit, squash, rebase, push — plus standalone utilities.
+- [wt hook](https://worktrunk.dev/hook.md): Run configured hooks.
+
+## Reference
+
+- [Extending Worktrunk](https://worktrunk.dev/extending.md): Three ways to add custom behavior: hooks for lifecycle automation, aliases for reusable commands, and custom subcommands for standalone tools.
+- [LLM Commit Messages](https://worktrunk.dev/llm-commits.md): Generate commit messages from diffs using any LLM. Integrates with wt merge, wt step commit, and wt step squash.
+- [Claude Code Integration](https://worktrunk.dev/claude-code.md): Worktrunk plugin for Claude Code: configuration skill, worktree isolation for agents, and activity tracking for wt list.
+- [Tips & Patterns](https://worktrunk.dev/tips-patterns.md): Practical recipes for Worktrunk workflows: aliases, shell integration, Zellij layouts, and parallel agent patterns.
+- [FAQ](https://worktrunk.dev/faq.md): Common questions about Worktrunk: comparison to git worktree and branch switching, bare repos, TUI support, and more.
diff --git a/docs/static/merge.md b/docs/static/merge.md
new file mode 120000
index 000000000..9e0e1882b
--- /dev/null
+++ b/docs/static/merge.md
@@ -0,0 +1 @@
+../../skills/worktrunk/reference/merge.md
\ No newline at end of file
diff --git a/docs/static/remove.md b/docs/static/remove.md
new file mode 120000
index 000000000..b920b4b8f
--- /dev/null
+++ b/docs/static/remove.md
@@ -0,0 +1 @@
+../../skills/worktrunk/reference/remove.md
\ No newline at end of file
diff --git a/docs/static/step.md b/docs/static/step.md
new file mode 120000
index 000000000..80a33651b
--- /dev/null
+++ b/docs/static/step.md
@@ -0,0 +1 @@
+../../skills/worktrunk/reference/step.md
\ No newline at end of file
diff --git a/docs/static/switch.md b/docs/static/switch.md
new file mode 120000
index 000000000..21ca6b257
--- /dev/null
+++ b/docs/static/switch.md
@@ -0,0 +1 @@
+../../skills/worktrunk/reference/switch.md
\ No newline at end of file
diff --git a/docs/static/tips-patterns.md b/docs/static/tips-patterns.md
new file mode 120000
index 000000000..fefb47c1c
--- /dev/null
+++ b/docs/static/tips-patterns.md
@@ -0,0 +1 @@
+../../skills/worktrunk/reference/tips-patterns.md
\ No newline at end of file
diff --git a/docs/static/worktrunk.md b/docs/static/worktrunk.md
new file mode 120000
index 000000000..277d1b2fe
--- /dev/null
+++ b/docs/static/worktrunk.md
@@ -0,0 +1 @@
+../../skills/worktrunk/reference/worktrunk.md
\ No newline at end of file
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index 637a06672..ff0fcec31 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -2068,9 +2068,20 @@ fn convert_console_blocks_in_docs(project_root: &Path) -> Vec<String> {
updated_files
}
-/// Sync all docs/content/*.md files to skills/worktrunk/reference/*.md
-/// (excluding _index.md which is a Zola template)
-/// Returns (errors, updated_files)
+/// Sorted `.md` page filenames in `docs/content/` (excluding `_index.md`
+/// and similar underscore-prefixed Zola section markers).
+fn docs_content_page_names(docs_dir: &Path) -> Vec<String> {
+ let mut names: Vec<String> = fs::read_dir(docs_dir)
+ .unwrap_or_else(|e| panic!("Failed to read {}: {}", docs_dir.display(), e))
+ .filter_map(|entry| {
+ let name = entry.ok()?.file_name().to_string_lossy().into_owned();
+ (name.ends_with(".md") && !name.starts_with('_')).then_some(name)
+ })
+ .collect();
+ names.sort();
+ names
+}
+
fn sync_skill_files(project_root: &Path) -> (Vec<String>, Vec<String>) {
let mut errors = Vec::new();
let mut updated_files = Vec::new();
@@ -2078,19 +2089,7 @@ fn sync_skill_files(project_root: &Path) -> (Vec<String>, Vec<String>) {
let docs_dir = project_root.join("docs/content");
let skill_dir = project_root.join("skills/worktrunk/reference");
- let mut entries: Vec<_> = fs::read_dir(&docs_dir)
- .unwrap_or_else(|e| panic!("Failed to read {}: {}", docs_dir.display(), e))
- .filter_map(|entry| {
- let entry = entry.ok()?;
- let name = entry.file_name().to_string_lossy().to_string();
- if name.ends_with(".md") && !name.starts_with('_') {
- Some(name)
- } else {
- None
- }
- })
- .collect();
- entries.sort();
+ let entries = docs_content_page_names(&docs_dir);
for name in &entries {
let skill_file = skill_dir.join(name);
@@ -2302,8 +2301,158 @@ fn sync_well_known_skills(project_root: &Path) -> Vec<String> {
updated_files
}
+/// Generate `docs/static/llms.txt` from `docs/content/*.md` front-matter,
+/// following the llms.txt spec (https://llmstxt.org/): H1, blockquote summary,
+/// optional intro prose, H2 section headings with bulleted link lists.
+///
+/// Link targets use the `.md` companion URLs (served via symlinks in
+/// `docs/static/*.md` → `skills/worktrunk/reference/*.md`).
+fn sync_llms_txt(project_root: &Path) -> Vec<String> {
+ use serde::Deserialize;
+ use std::collections::BTreeMap;
+
+ #[derive(Deserialize)]
+ struct ExtraFm {
+ group: Option<String>,
+ }
+
+ #[derive(Deserialize)]
+ struct Frontmatter {
+ title: String,
+ #[serde(default)]
+ description: Option<String>,
+ weight: i64,
+ #[serde(default)]
+ extra: Option<ExtraFm>,
+ }
+
+ let docs_dir = project_root.join("docs/content");
+ let config_path = project_root.join("docs/config.toml");
+
+ let config_content = fs::read_to_string(&config_path)
+ .unwrap_or_else(|e| panic!("Failed to read {}: {}", config_path.display(), e));
+ let site_config: toml::Value = toml::from_str(&config_content)
+ .unwrap_or_else(|e| panic!("Failed to parse {}: {}", config_path.display(), e));
+ let site_title = site_config
+ .get("title")
+ .and_then(|v| v.as_str())
+ .unwrap_or("Worktrunk");
+ let site_description = site_config
+ .get("extra")
+ .and_then(|e| e.get("site_description"))
+ .and_then(|v| v.as_str())
+ .unwrap_or("");
+ let base_url = site_config
+ .get("base_url")
+ .and_then(|v| v.as_str())
+ .unwrap_or("https://worktrunk.dev/")
+ .trim_end_matches('/');
+
+ let mut home_intro = String::new();
+ let mut pages: Vec<(String, Frontmatter)> = Vec::new();
+
+ for name in docs_content_page_names(&docs_dir) {
+ let path = docs_dir.join(&name);
+ let slug = name.trim_end_matches(".md").to_string();
+ let content = fs::read_to_string(&path)
+ .unwrap_or_else(|e| panic!("Failed to read {}: {}", path.display(), e));
+ let Some(rest) = content.strip_prefix("+++\n") else {
+ continue;
+ };
+ let Some((fm_text, body)) = rest.split_once("\n+++\n") else {
+ continue;
+ };
+ let fm: Frontmatter = toml::from_str(fm_text)
+ .unwrap_or_else(|e| panic!("Failed to parse frontmatter of {}: {}", path.display(), e));
+
+ // Ungrouped pages supply the document's intro prose instead of becoming bullets.
+ if fm.extra.as_ref().and_then(|e| e.group.as_deref()).is_none() {
+ home_intro = extract_intro_prose(body);
+ continue;
+ }
+
+ pages.push((slug, fm));
+ }
+
+ // Group pages by `extra.group`; order groups by their minimum weight so
+ // `## Commands` (weights 10–17) precedes `## Reference` (21–25) without
+ // hard-coding group names.
+ let mut groups: BTreeMap<String, Vec<(String, Frontmatter)>> = BTreeMap::new();
+ for (slug, fm) in pages {
+ let group = fm
+ .extra
+ .as_ref()
+ .and_then(|e| e.group.clone())
+ .expect("non-home pages must declare [extra] group");
+ groups.entry(group).or_default().push((slug, fm));
+ }
+ for pages in groups.values_mut() {
+ pages.sort_by_key(|(_, fm)| fm.weight);
+ }
+ let mut ordered: Vec<(String, Vec<(String, Frontmatter)>)> = groups.into_iter().collect();
+ ordered.sort_by_key(|(_, pages)| pages.first().map(|(_, fm)| fm.weight).unwrap_or(i64::MAX));
+
+ use std::fmt::Write;
+ let mut out = String::new();
+ writeln!(out, "# {site_title}\n").unwrap();
+ if !site_description.is_empty() {
+ writeln!(out, "> {site_description}\n").unwrap();
+ }
+ if !home_intro.is_empty() {
+ writeln!(out, "{home_intro}\n").unwrap();
+ }
+ for (group, pages) in ordered {
+ writeln!(out, "## {group}\n").unwrap();
+ for (slug, fm) in pages {
+ let desc = fm
+ .description
+ .as_deref()
+ .map(str::trim)
+ .filter(|s| !s.is_empty())
+ .map(|d| format!(": {d}"))
+ .unwrap_or_default();
+ writeln!(out, "- [{}]({base_url}/{slug}.md){desc}", fm.title).unwrap();
+ }
+ writeln!(out).unwrap();
+ }
+
+ let out = format!("{}\n", out.trim_end());
+
+ let dst = project_root.join("docs/static/llms.txt");
+ let current = fs::read_to_string(&dst).unwrap_or_default();
+ if current == out {
+ return vec![];
+ }
+ fs::write(&dst, &out).unwrap_or_else(|e| panic!("Failed to write {}: {}", dst.display(), e));
+ vec!["docs/static/llms.txt".to_string()]
+}
+
+/// Take the leading prose paragraphs of a page body, stopping at the first
+/// section heading or HTML block (figure, comment, etc.). The homepage uses
+/// this for the llms.txt intro.
+///
+/// Trims trailing lines ending with `:` — those typically introduce the
+/// content we just cut (a figure, code block, etc.) and dangle without it.
+fn extract_intro_prose(body: &str) -> String {
+ let mut lines: Vec<&str> = Vec::new();
+ for line in body.lines() {
+ let trimmed = line.trim_start();
+ if trimmed.starts_with("##") || trimmed.starts_with('<') || trimmed.starts_with("<!--") {
+ break;
+ }
+ lines.push(line);
+ }
+ while lines
+ .last()
+ .is_some_and(|l| l.trim_end().ends_with(':') || l.trim().is_empty())
+ {
+ lines.pop();
+ }
+ lines.join("\n").trim().to_string()
+}
+
/// Combined test: sync command pages (mod.rs → docs) then skill files (docs → skills)
-/// then .well-known/agent-skills/ (skills → docs/static).
+/// then .well-known/agent-skills/ (skills → docs/static) then llms.txt.
/// This ensures a single test run handles the full chain when mod.rs changes.
#[test]
fn test_command_pages_and_skill_files_are_in_sync() {
@@ -2324,6 +2473,9 @@ fn test_command_pages_and_skill_files_are_in_sync() {
// This reads the freshly-written skills from step 2
let well_known_files = sync_well_known_skills(project_root);
+ // Step 4: Generate docs/static/llms.txt from docs/content front-matter
+ let llms_files = sync_llms_txt(project_root);
+
// Aggregate results
let all_errors: Vec<_> = cmd_errors.into_iter().chain(skill_errors).collect();
let all_files: Vec<_> = cmd_files
@@ -2331,6 +2483,7 @@ fn test_command_pages_and_skill_files_are_in_sync() {
.chain(console_files)
.chain(skill_files)
.chain(well_known_files)
+ .chain(llms_files)
.collect();
if !all_errors.is_empty() {