Skip to content

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.md
index 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 named
by its `[list.custom-columns]` header (`columns = ["branch", "Ticket", "ci"]`),
and is exhaustive: only the listed columns render. Omit `columns` to keep the
default set, where custom columns append automatically.
diff --git a/plugins/worktrunk/skills/worktrunk/reference/list.md b/plugins/worktrunk/skills/worktrunk/reference/list.md
index 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 object
diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.md
index 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 named
by its `[list.custom-columns]` header (`columns = ["branch", "Ticket", "ci"]`),
and is exhaustive: only the listed columns render. Omit `columns` to keep the
default set, where custom columns append automatically.
diff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.md
index 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 object
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index 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 lines
content
.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: &regex::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.