Skip to content

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

fix: convert bare URLs to proper markdown links in docs (#664)

Maximilian Roosbada0d298d2f
diff --git a/.claude-plugin/CLAUDE.md b/.claude-plugin/CLAUDE.md
index 140e57dd1..3aed7e795 100644
--- a/.claude-plugin/CLAUDE.md
+++ b/.claude-plugin/CLAUDE.md
@@ -42,4 +42,4 @@ The hooks track Claude Code activity via git config (`worktrunk.status.{branch}`
**Problem**: If the user interrupts Claude Code (Escape/Ctrl+C), the πŸ€– status persists because there's no `UserInterrupt` hook. The `Stop` hook explicitly does not fire on user interrupt.
-**Tracking**: https://github.com/anthropics/claude-code/issues/9516
+**Tracking**: [claude-code#9516](https://github.com/anthropics/claude-code/issues/9516)
diff --git a/.claude-plugin/skills/worktrunk/reference/config.md b/.claude-plugin/skills/worktrunk/reference/config.md
index 9b54c49f3..89c4135f4 100644
--- a/.claude-plugin/skills/worktrunk/reference/config.md
+++ b/.claude-plugin/skills/worktrunk/reference/config.md
@@ -80,7 +80,7 @@ worktree-path = "../{{ branch | sanitize }}"
## LLM commit messages
-Generate commit messages automatically during merge. Requires an external CLI tool. See <https://worktrunk.dev/llm-commits/> for setup details and template customization.
+Generate commit messages automatically during merge. Requires an external CLI tool. See [LLM commits docs](https://worktrunk.dev/llm-commits/) for setup and template customization.
Using [llm](https://github.com/simonw/llm) (install: `pip install llm llm-anthropic`):
@@ -156,7 +156,7 @@ Commands approved for project hooks. Auto-populated when approving hooks on firs
approved-commands = ["npm ci", "npm test"]
```
-For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see <https://worktrunk.dev/hook/>.
+For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see [`wt hook` docs](https://worktrunk.dev/hook/).
### Custom prompt templates
diff --git a/dev/config.example.toml b/dev/config.example.toml
index f0a4160cb..ab134cc1b 100644
--- a/dev/config.example.toml
+++ b/dev/config.example.toml
@@ -38,21 +38,21 @@
#
# ## LLM commit messages
#
-# Generate commit messages automatically during merge. Requires an external CLI tool. See <https://worktrunk.dev/llm-commits/> for setup details and template customization.
+# Generate commit messages automatically during merge. Requires an external CLI tool. See LLM commits docs (https://worktrunk.dev/llm-commits/) for setup and template customization.
#
-# Using [llm](https://github.com/simonw/llm) (install: `pip install llm llm-anthropic`):
+# Using llm (https://github.com/simonw/llm) (install: `pip install llm llm-anthropic`):
#
# [commit-generation]
# command = "llm"
# args = ["-m", "claude-haiku-4.5"]
#
-# Using [aichat](https://github.com/sigoden/aichat):
+# Using aichat (https://github.com/sigoden/aichat):
#
# [commit-generation]
# command = "aichat"
# args = ["-m", "claude:claude-haiku-4.5"]
#
-# See [Custom prompt templates](#custom-prompt-templates) for inline template options.
+# See Custom prompt templates (#custom-prompt-templates) for inline template options.
#
# ## Commands
#
@@ -100,11 +100,11 @@
# [projects."github.com/user/repo"]
# approved-commands = ["npm ci", "npm test"]
#
-# For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see <https://worktrunk.dev/hook/>.
+# For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see `wt hook` docs (https://worktrunk.dev/hook/).
#
# ### Custom prompt templates
#
-# Templates use [minijinja](https://docs.rs/minijinja/) syntax.
+# Templates use minijinja (https://docs.rs/minijinja/) syntax.
#
# #### Commit template
#
diff --git a/docs/content/config.md b/docs/content/config.md
index 475215507..75f6655b0 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -88,7 +88,7 @@ worktree-path = "../{{ branch | sanitize }}"
## LLM commit messages
-Generate commit messages automatically during merge. Requires an external CLI tool. See <https://worktrunk.dev/llm-commits/> for setup details and template customization.
+Generate commit messages automatically during merge. Requires an external CLI tool. See [LLM commits docs](@/llm-commits.md) for setup and template customization.
Using [llm](https://github.com/simonw/llm) (install: `pip install llm llm-anthropic`):
@@ -164,7 +164,7 @@ Commands approved for project hooks. Auto-populated when approving hooks on firs
approved-commands = ["npm ci", "npm test"]
```
-For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see <https://worktrunk.dev/hook/>.
+For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see [`wt hook` docs](@/hook.md).
### Custom prompt templates
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 911d579e1..8f584d9b4 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1481,7 +1481,7 @@ worktree-path = "../{{ branch | sanitize }}"
## LLM commit messages
-Generate commit messages automatically during merge. Requires an external CLI tool. See <https://worktrunk.dev/llm-commits/> for setup details and template customization.
+Generate commit messages automatically during merge. Requires an external CLI tool. See [LLM commits docs](@/llm-commits.md) for setup and template customization.
Using [llm](https://github.com/simonw/llm) (install: `pip install llm llm-anthropic`):
@@ -1557,7 +1557,7 @@ Commands approved for project hooks. Auto-populated when approving hooks on firs
approved-commands = ["npm ci", "npm test"]
```
-For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see <https://worktrunk.dev/hook/>.
+For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see [`wt hook` docs](@/hook.md).
### Custom prompt templates
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index a0888cae6..3d43ff510 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -887,8 +887,9 @@ fn sync_readme_markers(
/// # Transform Rules
///
/// 1. Code fence markers (```` ``` ````, ```` ```toml ````) β†’ stripped entirely
-/// 2. All other lines β†’ prefixed with `# `
-/// 3. Trailing empty comment lines β†’ trimmed
+/// 2. Markdown links β†’ converted to plain URLs (config files aren't rendered as markdown)
+/// 3. All other lines β†’ prefixed with `# `
+/// 4. Trailing empty comment lines β†’ trimmed
fn transform_config_source_to_toml(source: &str) -> String {
let mut result = Vec::new();
let mut in_code_block = false;
@@ -902,6 +903,11 @@ fn transform_config_source_to_toml(source: &str) -> String {
continue;
}
+ // Convert markdown links to plain text for config file readability
+ // [Link text](@/page.md) β†’ Link text (https://worktrunk.dev/page/)
+ // [Link text](https://...) β†’ Link text (https://...)
+ let line = convert_markdown_links_for_config(line);
+
// Comment all lines
if line.is_empty() {
result.push(String::from("#"));
@@ -918,6 +924,36 @@ fn transform_config_source_to_toml(source: &str) -> String {
result.join("\n")
}
+/// Convert markdown links to plain text with URL in parentheses.
+///
+/// Config files aren't rendered as markdown, so links need to be readable as plain text.
+/// - `[Link text](@/page.md)` β†’ `Link text (https://worktrunk.dev/page/)`
+/// - `[Link text](https://example.com)` β†’ `Link text (https://example.com)`
+fn convert_markdown_links_for_config(line: &str) -> String {
+ use regex::Regex;
+ use std::sync::LazyLock;
+
+ static MARKDOWN_LINK: LazyLock<Regex> =
+ LazyLock::new(|| Regex::new(r"\[([^\]]+)\]\(([^)]+)\)").unwrap());
+
+ MARKDOWN_LINK
+ .replace_all(line, |caps: &regex::Captures| {
+ let text = &caps[1];
+ let url = &caps[2];
+
+ // Convert Zola @/ links to full URLs
+ let url = if let Some(path) = url.strip_prefix("@/") {
+ let page = path.trim_end_matches(".md");
+ format!("https://worktrunk.dev/{page}/")
+ } else {
+ url.to_string()
+ };
+
+ format!("{text} ({url})")
+ })
+ .to_string()
+}
+
/// Extract user config documentation from src/cli/mod.rs
///
/// The user config section is embedded in mod.rs between USER_CONFIG_START
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
index a1ef70adf..e675248ef 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -86,21 +86,21 @@ Creates ~/.config/worktrunk/config.toml with the following content:
#
# ## LLM commit messages
#
- # Generate commit messages automatically during merge. Requires an external CLI tool. See <https://worktrunk.dev/llm-commits/> for setup details and template customization.
+ # Generate commit messages automatically during merge. Requires an external CLI tool. See LLM commits docs (https://worktrunk.dev/llm-commits/) for setup and template customization.
#
- # Using [llm](https://github.com/simonw/llm) (install: `pip install llm llm-anthropic`):
+ # Using llm (https://github.com/simonw/llm) (install: `pip install llm llm-anthropic`):
#
# [commit-generation]
# command = "llm"
# args = ["-m", "claude-haiku-4.5"]
#
- # Using [aichat](https://github.com/sigoden/aichat):
+ # Using aichat (https://github.com/sigoden/aichat):
#
# [commit-generation]
# command = "aichat"
# args = ["-m", "claude:claude-haiku-4.5"]
#
- # See [Custom prompt templates](#custom-prompt-templates) for inline template options.
+ # See Custom prompt templates (#custom-prompt-templates) for inline template options.
#
# ## Commands
#
@@ -148,11 +148,11 @@ Creates ~/.config/worktrunk/config.toml with the following content:
# [projects."github.com/user/repo"]
# approved-commands = ["npm ci", "npm test"]
#
- # For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see <https://worktrunk.dev/hook/>.
+ # For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see `wt hook` docs (https://worktrunk.dev/hook/).
#
# ### Custom prompt templates
#
- # Templates use [minijinja](https://docs.rs/minijinja/) syntax.
+ # Templates use minijinja (https://docs.rs/minijinja/) syntax.
#
# #### Commit template
#
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index 6af84490c..b07ceaaf6 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -113,7 +113,7 @@ Controls where new worktrees are created. Paths are relative to the repository r
LLM commit messages
-Generate commit messages automatically during merge. Requires an external CLI tool. See <https://worktrunk.dev/llm-commits/> for setup details and template customization.
+Generate commit messages automatically during merge. Requires an external CLI tool. See LLM commits docs for setup and template customization.
Using llm (install: pip install llm llm-anthropic):
@@ -175,7 +175,7 @@ Commands approved for project hooks. Auto-populated when approving hooks on firs
[projects."github.com/user/repo"]
approved-commands = ["npm ci", "npm test"]
-For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at <repo>/.config/wt.toml. Run wt config create --project to create one, or see <https://worktrunk.dev/hook/>.
+For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at <repo>/.config/wt.toml. Run wt config create --project to create one, or see wt hook docs.
Custom prompt templates