Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs(reference): repair broken in-page anchors for custom columns and default_branch object (#4688)
viwe-monaid022f7683c7e
diff --git a/plugins/worktrunk/skills/worktrunk/reference/config.md b/plugins/worktrunk/skills/worktrunk/reference/config.mdindex 9c91427b5..50e2ab9de 100644--- a/plugins/worktrunk/skills/worktrunk/reference/config.md+++ b/plugins/worktrunk/skills/worktrunk/reference/config.md@@ -219,7 +219,7 @@ Valid built-in names:- `age` — Time since the last commit- `message` — The head commit's subject-A selection mixes built-ins with [custom columns](#custom-columns), each named+A selection mixes built-ins with [custom columns](#custom-columns-experimental), each namedby its `[list.custom-columns]` header (`columns = ["branch", "Ticket", "ci"]`),and is exhaustive: only the listed columns render. Omit `columns` to keep thedefault set, where custom columns append automatically.diff --git a/plugins/worktrunk/skills/worktrunk/reference/list.md b/plugins/worktrunk/skills/worktrunk/reference/list.mdindex fa43721d8..fa0b4c34a 100644--- a/plugins/worktrunk/skills/worktrunk/reference/list.md+++ b/plugins/worktrunk/skills/worktrunk/reference/list.md@@ -73,7 +73,7 @@ $ wt list --format=json| CI | PR/MR number colored by pipeline status; `--full` only || Path | Worktree directory || URL | Dev server URL from project config; dimmed if port is not listening |-| *(custom)* | User-defined [custom columns](#custom-columns) from `[list.custom-columns]` user config [experimental] |+| *(custom)* | User-defined [custom columns](#custom-columns-experimental) from `[list.custom-columns]` user config [experimental] || Commit | Short hash, abbreviated per `core.abbrev` || Age | Time since last commit || Message | Last commit message (truncated) |@@ -277,7 +277,7 @@ Item fields:| `remote` | string | Remote name, present only on remote-only branch rows || `head` | object/null | HEAD commit (see [head object](#head-object)); null for unborn branches || `worktree` | object | Worktree facts (see [worktree object](#worktree-object)); absent on branch-only rows |-| `default_branch` | object | Relation to the default branch (see [default_branch object](#default-branch-object)); absent on the default branch itself |+| `default_branch` | object | Relation to the default branch (see [default_branch object](#default_branch-object)); absent on the default branch itself || `upstream` | object | Tracking branch (see [upstream object](#upstream-object)); absent when none is configured || `pr` | object | Open PR/MR (see [pr object](#pr-object)); collected with `--full` || `checks` | object | CI pipeline (see [checks object](#checks-object)); collected with `--full` |@@ -388,7 +388,7 @@ Presentation only — every value here renders facts that appear elsewhere in th| `state` | string | The table's collapsed default-branch state (see [state values](#state-values)); absent when none applies || `symbols` | string | Raw status symbols without colors (e.g., `"!?↓"`) || `statusline` | string | Pre-formatted status with colors and links |-| `columns` | object | Rendered [custom column](#custom-columns) values keyed by header; empty cells omitted |+| `columns` | object | Rendered [custom column](#custom-columns-experimental) values keyed by header; empty cells omitted |### repo objectdiff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.mdindex 9c91427b5..50e2ab9de 100644--- a/skills/worktrunk/reference/config.md+++ b/skills/worktrunk/reference/config.md@@ -219,7 +219,7 @@ Valid built-in names:- `age` — Time since the last commit- `message` — The head commit's subject-A selection mixes built-ins with [custom columns](#custom-columns), each named+A selection mixes built-ins with [custom columns](#custom-columns-experimental), each namedby its `[list.custom-columns]` header (`columns = ["branch", "Ticket", "ci"]`),and is exhaustive: only the listed columns render. Omit `columns` to keep thedefault set, where custom columns append automatically.diff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.mdindex fa43721d8..fa0b4c34a 100644--- a/skills/worktrunk/reference/list.md+++ b/skills/worktrunk/reference/list.md@@ -73,7 +73,7 @@ $ wt list --format=json| CI | PR/MR number colored by pipeline status; `--full` only || Path | Worktree directory || URL | Dev server URL from project config; dimmed if port is not listening |-| *(custom)* | User-defined [custom columns](#custom-columns) from `[list.custom-columns]` user config [experimental] |+| *(custom)* | User-defined [custom columns](#custom-columns-experimental) from `[list.custom-columns]` user config [experimental] || Commit | Short hash, abbreviated per `core.abbrev` || Age | Time since last commit || Message | Last commit message (truncated) |@@ -277,7 +277,7 @@ Item fields:| `remote` | string | Remote name, present only on remote-only branch rows || `head` | object/null | HEAD commit (see [head object](#head-object)); null for unborn branches || `worktree` | object | Worktree facts (see [worktree object](#worktree-object)); absent on branch-only rows |-| `default_branch` | object | Relation to the default branch (see [default_branch object](#default-branch-object)); absent on the default branch itself |+| `default_branch` | object | Relation to the default branch (see [default_branch object](#default_branch-object)); absent on the default branch itself || `upstream` | object | Tracking branch (see [upstream object](#upstream-object)); absent when none is configured || `pr` | object | Open PR/MR (see [pr object](#pr-object)); collected with `--full` || `checks` | object | CI pipeline (see [checks object](#checks-object)); collected with `--full` |@@ -388,7 +388,7 @@ Presentation only — every value here renders facts that appear elsewhere in th| `state` | string | The table's collapsed default-branch state (see [state values](#state-values)); absent when none applies || `symbols` | string | Raw status symbols without colors (e.g., `"!?↓"`) || `statusline` | string | Pre-formatted status with colors and links |-| `columns` | object | Rendered [custom column](#custom-columns) values keyed by header; empty cells omitted |+| `columns` | object | Rendered [custom column](#custom-columns-experimental) values keyed by header; empty cells omitted |### repo objectdiff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rsindex fb3db4048..b788d871b 100644--- a/tests/integration_tests/readme_sync.rs+++ b/tests/integration_tests/readme_sync.rs@@ -2113,6 +2113,8 @@ fn finalize_skill_content(content: &str) -> String {// Remove "See also" section (just contains links to other pages)let content = remove_section(&content, "## See also");+ let content = rewrite_fragments_for_github(&content);+// Clean up multiple consecutive blank linescontent.lines()@@ -2127,6 +2129,80 @@ fn finalize_skill_content(content: &str) -> String {.join("\n")}+static IN_PAGE_LINK_PATTERN: LazyLock<Regex> =+ LazyLock::new(|| Regex::new(r"\]\(#([^)\s]+)\)").unwrap());++/// Anchor GitHub's slugger generates for a heading: lowercase, drop+/// punctuation except `-` and `_`, spaces to hyphens.+fn github_heading_anchor(heading: &str) -> String {+ heading+ .to_lowercase()+ .chars()+ .filter_map(|c| match c {+ ' ' => Some('-'),+ c if c.is_alphanumeric() || c == '-' || c == '_' => Some(c),+ _ => None,+ })+ .collect()+}++/// Rewrite in-page fragments from the site's heading slug to GitHub's.+///+/// Help text links headings by their worktrunk.dev id, where `slugHeading`+/// turns `_` into `-` and the `[experimental]` badge contributes no text.+/// Skill files render with GitHub's slugger, which keeps `_` and the literal+/// `[experimental]` suffix, so those links would otherwise land nowhere.+fn rewrite_fragments_for_github(content: &str) -> String {+ let mut site_to_github: BTreeMap<String, String> = BTreeMap::new();+ let mut in_code_block = false;+ for line in content.lines() {+ if line.trim_start().starts_with("```") {+ in_code_block = !in_code_block;+ continue;+ }+ if in_code_block {+ continue;+ }+ let Some(text) = line+ .strip_prefix('#')+ .map(|rest| rest.trim_start_matches('#'))+ .and_then(|rest| rest.strip_prefix(' '))+ else {+ continue;+ };+ let site = heading_to_anchor(&text.replace("[experimental]", ""));+ site_to_github+ .entry(site)+ .or_insert_with(|| github_heading_anchor(text.trim()));+ }++ IN_PAGE_LINK_PATTERN+ .replace_all(content, |caps: ®ex::Captures| {+ let fragment = &caps[1];+ let target = site_to_github+ .get(fragment)+ .map_or(fragment, String::as_str);+ format!("](#{target})")+ })+ .into_owned()+}++#[test]+fn test_skill_fragments_follow_github_slugs() {+ let content = r"See [custom columns](#custom-columns), [default_branch](#default-branch-object), and [CI](#ci-status).++### Custom columns [experimental]++### default_branch object++### CI status+";+ let rewritten = rewrite_fragments_for_github(content);+ assert!(rewritten.contains("[custom columns](#custom-columns-experimental)"));+ assert!(rewritten.contains("[default_branch](#default_branch-object)"));+ assert!(rewritten.contains("[CI](#ci-status)"));+}+/// Mirror the repo-root `skills/` tree into `plugins/worktrunk/skills/` as/// regular files, dereferencing symlinks, and delete mirror files whose/// source is gone.