Skip to content

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

Replace markdown links with Zola internal syntax

Maximilian Roosc436f6db3c2f
diff --git a/.config/lychee.toml b/.config/lychee.toml
index 7155a7960..ec016f9ad 100644
--- a/.config/lychee.toml
+++ b/.config/lychee.toml
@@ -15,6 +15,9 @@ max_cache_age = "1d"
# Exclude sites that block GitHub Actions or have reliability issues
exclude = [
+ # Zola internal links use @/ syntax (validated by `zola check`, not lychee)
+ "/@/",
+
# Private or authenticated GitHub resources
"github\\.com/anthropics/claude-code/issues",
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index cc321832e..143f0eb91 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -27,13 +27,13 @@ repos:
- repo: https://github.com/lycheeverse/lychee
rev: nightly
hooks:
- # Fast PR mode - only check worktrunk domains and local files
+ # Fast PR mode - only check worktrunk domains (internal links validated by zola check)
- id: lychee
name: lychee (PR mode)
types: [markdown]
args:
- --config=.config/lychee.toml
- - --include=^(https://(github\.com/max-sixty/worktrunk|worktrunk\.dev)|file://)
+ - --include=^https://(github\.com/max-sixty/worktrunk|worktrunk\.dev)
# Comprehensive mode - check all links with full config
# Run manually: pre-commit run --hook-stage manual lychee-all --all-files
- id: lychee
diff --git a/README.md b/README.md
index f30bf3ae6..28540d5da 100644
--- a/README.md
+++ b/README.md
@@ -506,7 +506,7 @@ Global Options:
Two distinct operations:
- **Switch to existing worktree** — Changes directory, nothing else
-- **Create new worktree** (`--create`) — Creates branch and worktree, runs [hooks](/hooks/)
+- **Create new worktree** (`--create`) — Creates branch and worktree, runs [hooks](@/hooks.md)
```
@@ -519,7 +519,7 @@ wt switch --create new-feature # Create branch and worktree
wt switch --create hotfix --base production
```
-For interactive selection, use [`wt select`](/select/).
+For interactive selection, use [`wt select`](@/select.md).
### Creating Worktrees
@@ -527,9 +527,9 @@ With `--create`, worktrunk:
1. Creates branch from `--base` (defaults to default branch)
2. Creates worktree at configured path
-3. Runs [post-create hooks](/hooks/#post-create) (blocking)
+3. Runs [post-create hooks](@/hooks.md#post-create) (blocking)
4. Switches to new directory
-5. Spawns [post-start hooks](/hooks/#post-start) (background)
+5. Spawns [post-start hooks](@/hooks.md#post-start) (background)
```bash
wt switch --create api-refactor
@@ -566,10 +566,10 @@ Arguments resolve by checking the filesystem before git branches:
### See Also
-- [wt select](/select/) — Interactive worktree selection
-- [wt list](/list/) — View all worktrees
-- [wt remove](/remove/) — Delete worktrees when done
-- [wt merge](/merge/) — Integrate changes back to main
+- [wt select](@/select.md) — Interactive worktree selection
+- [wt list](@/list.md) — View all worktrees
+- [wt remove](@/remove.md) — Delete worktrees when done
+- [wt merge](@/merge.md) — Integrate changes back to main
<!-- END AUTO-GENERATED -->
@@ -669,7 +669,7 @@ wt merge --no-commit
3. **Rebase** — Rebases onto the target branch. Conflicts abort immediately.
-4. **Pre-merge hooks** — Project commands run after rebase, before push. Failures abort. See [Hooks](/hooks/).
+4. **Pre-merge hooks** — Project commands run after rebase, before push. Failures abort. See [Hooks](@/hooks.md).
5. **Push** — Fast-forward push to the target branch. Non-fast-forward pushes are rejected.
@@ -681,9 +681,9 @@ Use `--no-commit` to skip steps 1-3 and only run hooks and push. Requires a clea
### See Also
-- [wt step](/step/) — Run individual merge steps (commit, squash, rebase, push)
-- [wt remove](/remove/) — Remove worktrees without merging
-- [wt switch](/switch/) — Navigate to other worktrees
+- [wt step](@/step.md) — Run individual merge steps (commit, squash, rebase, push)
+- [wt remove](@/remove.md) — Remove worktrees without merging
+- [wt switch](@/switch.md) — Navigate to other worktrees
<!-- END AUTO-GENERATED -->
@@ -780,8 +780,8 @@ If `repo.foo/` exists on branch `bar`, both `wt remove foo` and `wt remove bar`
### See Also
-- [wt merge](/merge/) — Remove worktree after merging
-- [wt list](/list/) — View all worktrees
+- [wt merge](@/merge.md) — Remove worktree after merging
+- [wt list](@/list.md) — View all worktrees
<!-- END AUTO-GENERATED -->
@@ -949,11 +949,11 @@ wt list --format=json | jq '.[] | select(.status.main_divergence == "Ahead")'
**Position fields:**
- `is_main` — Main worktree
- `is_current` — Current directory
-- `is_previous` — Previous worktree from [wt switch](/switch/)
+- `is_previous` — Previous worktree from [wt switch](@/switch.md)
### See Also
-- [wt select](/select/) — Interactive worktree picker with live preview
+- [wt select](@/select.md) — Interactive worktree picker with live preview
<!-- END AUTO-GENERATED -->
@@ -1039,7 +1039,7 @@ Personal settings like LLM commit generation, path templates, and default behavi
**Project config** — `.config/wt.toml` in repository root:
-Project-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See [Hooks](/hooks/) for details.
+Project-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See [Hooks](@/hooks.md) for details.
### LLM Commit Messages
@@ -1050,7 +1050,7 @@ Worktrunk can generate commit messages using an LLM. Enable in user config:
command = "llm"
```
-See [LLM Commits](/llm-commits/) for installation, provider setup, and customization.
+See [LLM Commits](@/llm-commits.md) for installation, provider setup, and customization.
<!-- END AUTO-GENERATED -->
@@ -1090,7 +1090,7 @@ Global Options:
-v, --verbose
Show commands and debug info
-Run individual workflow operations: commits, squashes, rebases, pushes, and [hooks](/hooks/).
+Run individual workflow operations: commits, squashes, rebases, pushes, and [hooks](@/hooks.md).
```
@@ -1122,12 +1122,12 @@ wt step push
**Git operations:**
-- `commit` — Stage and commit with [LLM-generated message](/llm-commits/)
-- `squash` — Squash all branch commits into one with [LLM-generated message](/llm-commits/)
+- `commit` — Stage and commit with [LLM-generated message](@/llm-commits.md)
+- `squash` — Squash all branch commits into one with [LLM-generated message](@/llm-commits.md)
- `rebase` — Rebase onto target branch
- `push` — Push to target branch (default: main)
-**Hooks** — run project commands defined in [`.config/wt.toml`](/hooks/):
+**Hooks** — run project commands defined in [`.config/wt.toml`](@/hooks.md):
- `post-create` — After worktree creation
- `post-start` — After switching to a worktree
@@ -1137,7 +1137,7 @@ wt step push
### See Also
-- [wt merge](/merge/) — Runs commit → squash → rebase → hooks → push → cleanup automatically
+- [wt merge](@/merge.md) — Runs commit → squash → rebase → hooks → push → cleanup automatically
<!-- END AUTO-GENERATED -->
diff --git a/docs/content/advanced.md b/docs/content/advanced.md
index bf9bd838e..fa037d1d2 100644
--- a/docs/content/advanced.md
+++ b/docs/content/advanced.md
@@ -82,4 +82,4 @@ Add to `~/.claude/settings.json`:
Type to filter, use arrow keys or `j`/`k` to navigate, Enter to switch. Preview tabs show working tree changes, commit history, or branch diff — toggle with `1`/`2`/`3`.
-See [wt select](/commands/#wt-select) for full keyboard shortcuts and details.
+See [wt select](@/select.md) for full keyboard shortcuts and details.
diff --git a/docs/content/concepts.md b/docs/content/concepts.md
index 713c025f6..4b3667e29 100644
--- a/docs/content/concepts.md
+++ b/docs/content/concepts.md
@@ -36,12 +36,12 @@ Worktrunk addresses worktrees by branch name rather than filesystem path, using
Beyond simplifying common tasks, Worktrunk adds features that git worktrees don't provide.
-**[LLM commit messages](/llm-commits/)** generate commit messages from diffs using external tools like [llm](https://llm.datasette.io/). Works for regular commits and squash commits during merge.
+**[LLM commit messages](@/llm-commits.md)** generate commit messages from diffs using external tools like [llm](https://llm.datasette.io/). Works for regular commits and squash commits during merge.
-**[Lifecycle hooks](/hooks/)** run project-defined commands at key points: worktree creation, switching, and merging. Use them for dependency installation, dev servers, formatters, tests, or deployment.
+**[Lifecycle hooks](@/hooks.md)** run project-defined commands at key points: worktree creation, switching, and merging. Use them for dependency installation, dev servers, formatters, tests, or deployment.
-**[Unified status](/list/)** shows changes, ahead/behind counts, diff stats, and commit messages across all worktrees. With `--full`, it adds CI status (GitHub/GitLab), conflict detection, and line-level diffs against main.
+**[Unified status](@/list.md)** shows changes, ahead/behind counts, diff stats, and commit messages across all worktrees. With `--full`, it adds CI status (GitHub/GitLab), conflict detection, and line-level diffs against main.
**Safe cleanup** validates that changes are integrated before deleting worktrees and branches.
-**[Merge workflow](/merge/)** handles the full pipeline: stage, squash, rebase, run hooks, push, and clean up.
+**[Merge workflow](@/merge.md)** handles the full pipeline: stage, squash, rebase, run hooks, push, and clean up.
diff --git a/docs/content/config.md b/docs/content/config.md
index 8ec83ea1b..4f754d2b1 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -55,7 +55,7 @@ Personal settings like LLM commit generation, path templates, and default behavi
**Project config** — `.config/wt.toml` in repository root:
-Project-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See [Hooks](/hooks/) for details.
+Project-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See [Hooks](@/hooks.md) for details.
## LLM Commit Messages
@@ -66,7 +66,7 @@ Worktrunk can generate commit messages using an LLM. Enable in user config:
command = "llm"
```
-See [LLM Commits](/llm-commits/) for installation, provider setup, and customization.
+See [LLM Commits](@/llm-commits.md) for installation, provider setup, and customization.
---
diff --git a/docs/content/configuration.md b/docs/content/configuration.md
index cfb4b5820..890e3bc65 100644
--- a/docs/content/configuration.md
+++ b/docs/content/configuration.md
@@ -83,7 +83,7 @@ command = "llm"
args = ["-m", "claude-haiku-4.5"]
```
-See [LLM Commit Messages](/llm-commits/) for setup details and template customization.
+See [LLM Commit Messages](@/llm-commits.md) for setup details and template customization.
### Approved Commands
@@ -114,7 +114,7 @@ test = "npm test"
lint = "npm run lint"
```
-See [Hooks](/hooks/) for complete documentation on hook types, execution order, and template variables.
+See [Hooks](@/hooks.md) for complete documentation on hook types, execution order, and template variables.
## Shell Integration
diff --git a/docs/content/list.md b/docs/content/list.md
index 0cf6b8290..e40dc8018 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -122,11 +122,11 @@ wt list --format=json | jq '.[] | select(.status.main_divergence == "Ahead")'
**Position fields:**
- `is_main` — Main worktree
- `is_current` — Current directory
-- `is_previous` — Previous worktree from [wt switch](/switch/)
+- `is_previous` — Previous worktree from [wt switch](@/switch.md)
## See Also
-- [wt select](/select/) — Interactive worktree picker with live preview
+- [wt select](@/select.md) — Interactive worktree picker with live preview
---
diff --git a/docs/content/llm-commits.md b/docs/content/llm-commits.md
index 37bcee1be..3e66e2c19 100644
--- a/docs/content/llm-commits.md
+++ b/docs/content/llm-commits.md
@@ -91,7 +91,7 @@ Squashes branch commits into one with LLM-generated message:
$ wt step squash
```
-See [wt merge](/merge/) and [wt step](/step/) for full documentation.
+See [wt merge](@/merge.md) and [wt step](@/step.md) for full documentation.
## Prompt templates
diff --git a/docs/content/merge.md b/docs/content/merge.md
index 5b81bfd04..b622de4bc 100644
--- a/docs/content/merge.md
+++ b/docs/content/merge.md
@@ -48,7 +48,7 @@ wt merge --no-commit
3. **Rebase** — Rebases onto the target branch. Conflicts abort immediately.
-4. **Pre-merge hooks** — Project commands run after rebase, before push. Failures abort. See [Hooks](/hooks/).
+4. **Pre-merge hooks** — Project commands run after rebase, before push. Failures abort. See [Hooks](@/hooks.md).
5. **Push** — Fast-forward push to the target branch. Non-fast-forward pushes are rejected.
@@ -60,9 +60,9 @@ Use `--no-commit` to skip steps 1-3 and only run hooks and push. Requires a clea
## See Also
-- [wt step](/step/) — Run individual merge steps (commit, squash, rebase, push)
-- [wt remove](/remove/) — Remove worktrees without merging
-- [wt switch](/switch/) — Navigate to other worktrees
+- [wt step](@/step.md) — Run individual merge steps (commit, squash, rebase, push)
+- [wt remove](@/remove.md) — Remove worktrees without merging
+- [wt switch](@/switch.md) — Navigate to other worktrees
---
diff --git a/docs/content/quickstart.md b/docs/content/quickstart.md
index afabe7582..652b986cb 100644
--- a/docs/content/quickstart.md
+++ b/docs/content/quickstart.md
@@ -80,11 +80,8 @@ When you're done with a worktree (e.g., after merging via CI):
Worktrunk checks if your changes are already on main before deleting the branch.
-<!-- TODO: Add shortcuts (@, -, ^) somewhere more prominent in the docs -
- too early for quickstart but should be discoverable -->
-
## Next steps
-- Understand [why worktrees matter](/concepts/) and how Worktrunk improves on plain git
-- Set up [project hooks](/hooks/) for automated setup
-- Explore advanced features: [LLM commit messages](/llm-commits/), [local merging](/merge/), [fzf-like picker](/select/), [Claude Code integration](/advanced/#claude-code-integration)
+- Understand [why worktrees matter](@/concepts.md) and how Worktrunk improves on plain git
+- Set up [project hooks](@/hooks.md) for automated setup
+- Explore advanced features: [LLM commit messages](@/llm-commits.md), [local merging](@/merge.md), [fzf-like picker](@/select.md), [Claude Code integration](@/advanced.md#claude-code-integration)
diff --git a/docs/content/remove.md b/docs/content/remove.md
index 51f782414..f5aaa0377 100644
--- a/docs/content/remove.md
+++ b/docs/content/remove.md
@@ -61,8 +61,8 @@ If `repo.foo/` exists on branch `bar`, both `wt remove foo` and `wt remove bar`
## See Also
-- [wt merge](/merge/) — Remove worktree after merging
-- [wt list](/list/) — View all worktrees
+- [wt merge](@/merge.md) — Remove worktree after merging
+- [wt list](@/list.md) — View all worktrees
---
diff --git a/docs/content/select.md b/docs/content/select.md
index 7fc628948..5d7466238 100644
--- a/docs/content/select.md
+++ b/docs/content/select.md
@@ -40,8 +40,8 @@ Toggle between views with number keys:
## See Also
-- [wt list](/list/) — Static table view with all worktree metadata
-- [wt switch](/switch/) — Direct switching when you know the target branch
+- [wt list](@/list.md) — Static table view with all worktree metadata
+- [wt switch](@/switch.md) — Direct switching when you know the target branch
---
diff --git a/docs/content/step.md b/docs/content/step.md
index 2d632d403..c782070fd 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -8,7 +8,7 @@ group = "Commands"
<!-- ⚠️ AUTO-GENERATED from `wt step --help-page` — edit src/cli.rs to update -->
-Run individual workflow operations: commits, squashes, rebases, pushes, and [hooks](/hooks/).
+Run individual workflow operations: commits, squashes, rebases, pushes, and [hooks](@/hooks.md).
## Examples
@@ -38,12 +38,12 @@ wt step push
**Git operations:**
-- `commit` — Stage and commit with [LLM-generated message](/llm-commits/)
-- `squash` — Squash all branch commits into one with [LLM-generated message](/llm-commits/)
+- `commit` — Stage and commit with [LLM-generated message](@/llm-commits.md)
+- `squash` — Squash all branch commits into one with [LLM-generated message](@/llm-commits.md)
- `rebase` — Rebase onto target branch
- `push` — Push to target branch (default: main)
-**Hooks** — run project commands defined in [`.config/wt.toml`](/hooks/):
+**Hooks** — run project commands defined in [`.config/wt.toml`](@/hooks.md):
- `post-create` — After worktree creation
- `post-start` — After switching to a worktree
@@ -53,7 +53,7 @@ wt step push
## See Also
-- [wt merge](/merge/) — Runs commit → squash → rebase → hooks → push → cleanup automatically
+- [wt merge](@/merge.md) — Runs commit → squash → rebase → hooks → push → cleanup automatically
---
diff --git a/docs/content/switch.md b/docs/content/switch.md
index fcb2e3163..d72a57216 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -11,7 +11,7 @@ group = "Commands"
Two distinct operations:
- **Switch to existing worktree** — Changes directory, nothing else
-- **Create new worktree** (`--create`) — Creates branch and worktree, runs [hooks](/hooks/)
+- **Create new worktree** (`--create`) — Creates branch and worktree, runs [hooks](@/hooks.md)
## Examples
@@ -22,7 +22,7 @@ wt switch --create new-feature # Create branch and worktree
wt switch --create hotfix --base production
```
-For interactive selection, use [`wt select`](/select/).
+For interactive selection, use [`wt select`](@/select.md).
## Creating Worktrees
@@ -30,9 +30,9 @@ With `--create`, worktrunk:
1. Creates branch from `--base` (defaults to default branch)
2. Creates worktree at configured path
-3. Runs [post-create hooks](/hooks/#post-create) (blocking)
+3. Runs [post-create hooks](@/hooks.md#post-create) (blocking)
4. Switches to new directory
-5. Spawns [post-start hooks](/hooks/#post-start) (background)
+5. Spawns [post-start hooks](@/hooks.md#post-start) (background)
```bash
wt switch --create api-refactor
@@ -69,10 +69,10 @@ Arguments resolve by checking the filesystem before git branches:
## See Also
-- [wt select](/select/) — Interactive worktree selection
-- [wt list](/list/) — View all worktrees
-- [wt remove](/remove/) — Delete worktrees when done
-- [wt merge](/merge/) — Integrate changes back to main
+- [wt select](@/select.md) — Interactive worktree selection
+- [wt list](@/list.md) — View all worktrees
+- [wt remove](@/remove.md) — Delete worktrees when done
+- [wt merge](@/merge.md) — Integrate changes back to main
---
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index 70688ac19..6b2314768 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -61,7 +61,7 @@ wt config var set marker "✅" --branch feature # Specific branch
git config worktrunk.marker.feature "💬" # Direct git config
```
-See [Claude Code Integration](/advanced/#claude-code-integration) for plugin installation.
+See [Claude Code Integration](@/advanced.md#claude-code-integration) for plugin installation.
## Monitor CI across branches
@@ -77,7 +77,7 @@ Shows PR/CI status for all branches, including those without worktrees. The CI c
wt list --format=json
```
-Structured output for dashboards, statuslines, and scripts. See [wt list](/commands/#wt-list) for query examples.
+Structured output for dashboards, statuslines, and scripts. See [wt list](@/list.md) for query examples.
## Task runners in hooks
diff --git a/src/cli.rs b/src/cli.rs
index 265a11af5..7fe324a76 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -701,7 +701,7 @@ Personal settings like LLM commit generation, path templates, and default behavi
**Project config** — `.config/wt.toml` in repository root:
-Project-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See [Hooks](/hooks/) for details.
+Project-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See [Hooks](@/hooks.md) for details.
## LLM Commit Messages
@@ -712,7 +712,7 @@ Worktrunk can generate commit messages using an LLM. Enable in user config:
command = "llm"
```
-See [LLM Commits](/llm-commits/) for installation, provider setup, and customization.
+See [LLM Commits](@/llm-commits.md) for installation, provider setup, and customization.
"#
)]
Config {
@@ -723,7 +723,7 @@ See [LLM Commits](/llm-commits/) for installation, provider setup, and customiza
/// Run individual workflow operations
#[command(
name = "step",
- after_long_help = r#"Run individual workflow operations: commits, squashes, rebases, pushes, and [hooks](/hooks/).
+ after_long_help = r#"Run individual workflow operations: commits, squashes, rebases, pushes, and [hooks](@/hooks.md).
## Examples
@@ -753,12 +753,12 @@ wt step push
**Git operations:**
-- `commit` — Stage and commit with [LLM-generated message](/llm-commits/)
-- `squash` — Squash all branch commits into one with [LLM-generated message](/llm-commits/)
+- `commit` — Stage and commit with [LLM-generated message](@/llm-commits.md)
+- `squash` — Squash all branch commits into one with [LLM-generated message](@/llm-commits.md)
- `rebase` — Rebase onto target branch
- `push` — Push to target branch (default: main)
-**Hooks** — run project commands defined in [`.config/wt.toml`](/hooks/):
+**Hooks** — run project commands defined in [`.config/wt.toml`](@/hooks.md):
- `post-create` — After worktree creation
- `post-start` — After switching to a worktree
@@ -768,7 +768,7 @@ wt step push
## See Also
-- [wt merge](/merge/) — Runs commit → squash → rebase → hooks → push → cleanup automatically
+- [wt merge](@/merge.md) — Runs commit → squash → rebase → hooks → push → cleanup automatically
"#
)]
Step {
@@ -813,8 +813,8 @@ Toggle between views with number keys:
## See Also
-- [wt list](/list/) — Static table view with all worktree metadata
-- [wt switch](/switch/) — Direct switching when you know the target branch
+- [wt list](@/list.md) — Static table view with all worktree metadata
+- [wt switch](@/switch.md) — Direct switching when you know the target branch
"#
)]
Select,
@@ -935,11 +935,11 @@ wt list --format=json | jq '.[] | select(.status.main_divergence == "Ahead")'
**Position fields:**
- `is_main` — Main worktree
- `is_current` — Current directory
-- `is_previous` — Previous worktree from [wt switch](/switch/)
+- `is_previous` — Previous worktree from [wt switch](@/switch.md)
## See Also
-- [wt select](/select/) — Interactive worktree picker with live preview
+- [wt select](@/select.md) — Interactive worktree picker with live preview
"#
)]
#[command(args_conflicts_with_subcommands = true)]
@@ -979,7 +979,7 @@ wt list --format=json | jq '.[] | select(.status.main_divergence == "Ahead")'
#[command(after_long_help = r#"Two distinct operations:
- **Switch to existing worktree** — Changes directory, nothing else
-- **Create new worktree** (`--create`) — Creates branch and worktree, runs [hooks](/hooks/)
+- **Create new worktree** (`--create`) — Creates branch and worktree, runs [hooks](@/hooks.md)
## Examples
@@ -990,7 +990,7 @@ wt switch --create new-feature # Create branch and worktree
wt switch --create hotfix --base production
```
-For interactive selection, use [`wt select`](/select/).
+For interactive selection, use [`wt select`](@/select.md).
## Creating Worktrees
@@ -998,9 +998,9 @@ With `--create`, worktrunk:
1. Creates branch from `--base` (defaults to default branch)
2. Creates worktree at configured path
-3. Runs [post-create hooks](/hooks/#post-create) (blocking)
+3. Runs [post-create hooks](@/hooks.md#post-create) (blocking)
4. Switches to new directory
-5. Spawns [post-start hooks](/hooks/#post-start) (background)
+5. Spawns [post-start hooks](@/hooks.md#post-start) (background)
```console
wt switch --create api-refactor
@@ -1037,10 +1037,10 @@ Arguments resolve by checking the filesystem before git branches:
## See Also
-- [wt select](/select/) — Interactive worktree selection
-- [wt list](/list/) — View all worktrees
-- [wt remove](/remove/) — Delete worktrees when done
-- [wt merge](/merge/) — Integrate changes back to main
+- [wt select](@/select.md) — Interactive worktree selection
+- [wt list](@/list.md) — View all worktrees
+- [wt remove](@/remove.md) — Delete worktrees when done
+- [wt merge](@/merge.md) — Integrate changes back to main
"#)]
Switch {
/// Branch or worktree name
@@ -1127,8 +1127,8 @@ If `repo.foo/` exists on branch `bar`, both `wt remove foo` and `wt remove bar`
## See Also
-- [wt merge](/merge/) — Remove worktree after merging
-- [wt list](/list/) — View all worktrees
+- [wt merge](@/merge.md) — Remove worktree after merging
+- [wt list](@/list.md) — View all worktrees
"#
)]
Remove {
@@ -1191,7 +1191,7 @@ wt merge --no-commit
3. **Rebase** — Rebases onto the target branch. Conflicts abort immediately.
-4. **Pre-merge hooks** — Project commands run after rebase, before push. Failures abort. See [Hooks](/hooks/).
+4. **Pre-merge hooks** — Project commands run after rebase, before push. Failures abort. See [Hooks](@/hooks.md).
5. **Push** — Fast-forward push to the target branch. Non-fast-forward pushes are rejected.
@@ -1203,9 +1203,9 @@ Use `--no-commit` to skip steps 1-3 and only run hooks and push. Requires a clea
## See Also
-- [wt step](/step/) — Run individual merge steps (commit, squash, rebase, push)
-- [wt remove](/remove/) — Remove worktrees without merging
-- [wt switch](/switch/) — Navigate to other worktrees
+- [wt step](@/step.md) — Run individual merge steps (commit, squash, rebase, push)
+- [wt remove](@/remove.md) — Remove worktrees without merging
+- [wt switch](@/switch.md) — Navigate to other worktrees
"#
)]
Merge {
diff --git a/src/main.rs b/src/main.rs
index a47f9e727..fb1299076 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -185,8 +185,7 @@ fn handle_help_page(args: &[String]) {
};
// Get the after_long_help content
- // Transform ```console to ```bash for Zola compatibility
- // Add HTML colors for CI status dots
+ // Transform for web docs: console→bash, status colors
let after_help = sub
.get_after_long_help()
.map(|s| {
diff --git a/src/md_help.rs b/src/md_help.rs
index 0de2021e0..e4cb6c58b 100644
--- a/src/md_help.rs
+++ b/src/md_help.rs
@@ -47,7 +47,7 @@ pub fn render_markdown_in_help(help: &str) -> String {
colorize_status_symbols(&result)
}
-/// Render inline markdown formatting (bold, inline code)
+/// Render inline markdown formatting (bold, inline code, links)
fn render_inline_formatting(line: &str) -> String {
let bold = Style::new().bold();
let code = Style::new().dimmed();
@@ -78,6 +78,45 @@ fn render_inline_formatting(line: &str) -> String {
bold_content.push(c);
}
result.push_str(&format!("{bold}{bold_content}{bold:#}"));
+ } else if ch == '[' {
+ // Markdown link: [text](url) -> render just text
+ // Non-links like [text] or [text are preserved literally
+ let mut link_text = String::new();
+ let mut found_close = false;
+ let mut bracket_depth = 0;
+ for c in chars.by_ref() {
+ if c == '[' {
+ bracket_depth += 1;
+ link_text.push(c);
+ } else if c == ']' {
+ if bracket_depth == 0 {
+ found_close = true;
+ break;
+ }
+ bracket_depth -= 1;
+ link_text.push(c);
+ } else {
+ link_text.push(c);
+ }
+ }
+ if found_close && chars.peek() == Some(&'(') {
+ chars.next(); // consume '('
+ // Skip URL until closing ')'
+ for c in chars.by_ref() {
+ if c == ')' {
+ break;
+ }
+ }
+ // Render just the link text
+ result.push_str(&link_text);
+ } else {
+ // Not a valid link, output literally
+ result.push('[');
+ result.push_str(&link_text);
+ if found_close {
+ result.push(']');
+ }
+ }
} else {
result.push(ch);
}
@@ -155,3 +194,48 @@ fn colorize_status_symbols(text: &str) -> String {
&format!("{working_tree}✘{working_tree:#} Deleted"),
)
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn test_render_inline_formatting_strips_links() {
+ assert_eq!(render_inline_formatting("[text](url)"), "text");
+ assert_eq!(
+ render_inline_formatting("See [Hooks](@/hooks.md) for details"),
+ "See Hooks for details"
+ );
+ }
+
+ #[test]
+ fn test_render_inline_formatting_nested_brackets() {
+ assert_eq!(
+ render_inline_formatting("[text [with brackets]](url)"),
+ "text [with brackets]"
+ );
+ }
+
+ #[test]
+ fn test_render_inline_formatting_multiple_links() {
+ assert_eq!(render_inline_formatting("[a](b) and [c](d)"), "a and c");
+ }
+
+ #[test]
+ fn test_render_inline_formatting_malformed_links() {
+ // Missing URL - preserved literally
+ assert_eq!(render_inline_formatting("[text]"), "[text]");
+ // Unclosed bracket - preserved literally
+ assert_eq!(render_inline_formatting("[text"), "[text");
+ // Not followed by ( - preserved literally
+ assert_eq!(render_inline_formatting("[text] more"), "[text] more");
+ }
+
+ #[test]
+ fn test_render_inline_formatting_preserves_bold_and_code() {
+ assert_eq!(
+ render_inline_formatting("**bold** and `code`"),
+ "\u{1b}[1mbold\u{1b}[0m and \u{1b}[2mcode\u{1b}[0m"
+ );
+ }
+}
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 8419b7837..5d7843401 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -81,7 +81,7 @@ Personal settings like LLM commit generation, path templates, and default behavi
Project config — .config/wt.toml in repository root:
-Project-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See [Hooks](/hooks/) for details.
+Project-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See Hooks for details.
LLM Commit Messages
@@ -90,4 +90,4 @@ Worktrunk can generate commit messages using an LLM. Enable in user config:
[commit-generation]
command = "llm"
-See [LLM Commits](/llm-commits/) for installation, provider setup, and customization.
+See LLM Commits for installation, provider setup, and customization.
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
index e3a352d4b..a4d2a0ac4 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
@@ -161,8 +161,8 @@ Query structured data with --format=json:
Position fields:
- is_main — Main worktree
- is_current — Current directory
-- is_previous — Previous worktree from [wt switch](/switch/)
+- is_previous — Previous worktree from wt switch
See Also
-- [wt select](/select/) — Interactive worktree picker with live preview
+- wt select — Interactive worktree picker with live preview
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
index f829c661a..a63697f82 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
@@ -95,7 +95,7 @@ Skip git operations, only run hooks and push:
3. Rebase — Rebases onto the target branch. Conflicts abort immediately.
-4. Pre-merge hooks — Project commands run after rebase, before push. Failures abort. See [Hooks](/hooks/).
+4. Pre-merge hooks — Project commands run after rebase, before push. Failures abort. See Hooks.
5. Push — Fast-forward push to the target branch. Non-fast-forward pushes are rejected.
@@ -107,6 +107,6 @@ Use --no-commit to skip steps 1-3 and only run hooks and push. Requires
See Also
-- [wt step](/step/) — Run individual merge steps (commit, squash, rebase, push)
-- [wt remove](/remove/) — Remove worktrees without merging
-- [wt switch](/switch/) — Navigate to other worktrees
+- wt step — Run individual merge steps (commit, squash, rebase, push)
+- wt remove — Remove worktrees without merging
+- wt switch — Navigate to other worktrees
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
index dcad0b8a9..01dafca66 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
@@ -92,5 +92,5 @@ If repo.foo/ exists on branch bar, both wt remove foo an
See Also
-- [wt merge](/merge/) — Remove worktree after merging
-- [wt list](/list/) — View all worktrees
+- wt merge — Remove worktree after merging
+- wt list — View all worktrees
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_long.snap b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
index e55525fdd..5b796018f 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -45,7 +45,7 @@ Usage: wt step [OPTIONS] <COMMAND>
-v, --verbose
Show commands and debug info
-Run individual workflow operations: commits, squashes, rebases, pushes, and [hooks](/hooks/).
+Run individual workflow operations: commits, squashes, rebases, pushes, and hooks.
Examples
@@ -69,12 +69,12 @@ Manual merge workflow with review between steps:
Git operations:
-- commit — Stage and commit with [LLM-generated message](/llm-commits/)
-- squash — Squash all branch commits into one with [LLM-generated message](/llm-commits/)
+- commit — Stage and commit with LLM-generated message
+- squash — Squash all branch commits into one with LLM-generated message
- rebase — Rebase onto target branch
- push — Push to target branch (default: main)
-Hooks — run project commands defined in [.config/wt.toml](/hooks/):
+Hooks — run project commands defined in `.config/wt.toml`:
- post-create — After worktree creation
- post-start — After switching to a worktree
@@ -84,4 +84,4 @@ Manual merge workflow with review between steps:
See Also
-- [wt merge](/merge/) — Runs commit → squash → rebase → hooks → push → cleanup automatically
+- wt merge — Runs commit → squash → rebase → hooks → push → cleanup automatically
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
index 6a0dd0d0f..7179e071a 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -60,7 +60,7 @@ Usage: wt switch [OPTIONS] <BRANCH>
Two distinct operations:
- Switch to existing worktree — Changes directory, nothing else
-- Create new worktree (--create) — Creates branch and worktree, runs [hooks](/hooks/)
+- Create new worktree (--create) — Creates branch and worktree, runs hooks
Examples
@@ -69,7 +69,7 @@ Two distinct operations:
wt switch --create new-feature # Create branch and worktree
wt switch --create hotfix --base production
-For interactive selection, use [wt select](/select/).
+For interactive selection, use `wt select`.
Creating Worktrees
@@ -77,9 +77,9 @@ With --create, worktrunk:
1. Creates branch from --base (defaults to default branch)
2. Creates worktree at configured path
-3. Runs [post-create hooks](/hooks/#post-create) (blocking)
+3. Runs post-create hooks (blocking)
4. Switches to new directory
-5. Spawns [post-start hooks](/hooks/#post-start) (background)
+5. Spawns post-start hooks (background)
wt switch --create api-refactor
wt switch --create fix --base release-2.0
@@ -112,7 +112,7 @@ Arguments resolve by checking the filesystem before git branches:
See Also
-- [wt select](/select/) — Interactive worktree selection
-- [wt list](/list/) — View all worktrees
-- [wt remove](/remove/) — Delete worktrees when done
-- [wt merge](/merge/) — Integrate changes back to main
+- wt select — Interactive worktree selection
+- wt list — View all worktrees
+- wt remove — Delete worktrees when done
+- wt merge — Integrate changes back to main