Skip to content

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

Widen Zola link regex to tolerate code spans in link text (#2327)

Maximilian Roos1a0a3e2f8339
diff --git a/docs/content/extending.md b/docs/content/extending.md
index 96bc9c5cf..3cace0a60 100644
--- a/docs/content/extending.md
+++ b/docs/content/extending.md
@@ -23,7 +23,7 @@ Worktrunk has three extension mechanisms.
| **Shareable via repo** | `.config/wt.toml` | `.config/wt.toml` | Distribute the binary |
| **Language** | Shell commands | Shell commands | Any |
-Hooks and aliases share the TOML config file, the [template engine](@/hook.md#template-variables) (variables, filters, and functions), the `[[block]]` [pipeline syntax](@/hook.md#pipeline-ordering) (blocks run in order, keys within a block run concurrently), and the approval model: user config is trusted; project config requires approval on first run. When both sources define the same name, both run — user first.
+Hooks and aliases share the TOML config file, the [template engine](@/hook.md#template-variables) (variables, filters, and functions), the [`[[block]]` pipeline syntax](@/hook.md#pipeline-ordering) (blocks run in order, keys within a block run concurrently), and the approval model: user config is trusted; project config requires approval on first run. When both sources define the same name, both run — user first.
## Hooks
@@ -97,7 +97,7 @@ Tokens after `--` forward unconditionally, bypassing any binding. Writing `wt de
### Multi-step pipelines
-`[[aliases.NAME]]` defines a pipeline using the same `[[block]]` [semantics as hooks](@/hook.md#pipeline-ordering) — blocks run in order, keys within a block run concurrently, a step failure aborts the remainder:
+`[[aliases.NAME]]` defines a pipeline using the [same `[[block]]` semantics as hooks](@/hook.md#pipeline-ordering) — blocks run in order, keys within a block run concurrently, a step failure aborts the remainder:
```toml
[[aliases.release]]
diff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.md
index c83922f91..bf64d82be 100644
--- a/skills/worktrunk/reference/extending.md
+++ b/skills/worktrunk/reference/extending.md
@@ -16,7 +16,7 @@ Worktrunk has three extension mechanisms.
| **Shareable via repo** | `.config/wt.toml` | `.config/wt.toml` | Distribute the binary |
| **Language** | Shell commands | Shell commands | Any |
-Hooks and aliases share the TOML config file, the [template engine](https://worktrunk.dev/hook/#template-variables) (variables, filters, and functions), the `[[block]]` [pipeline syntax](https://worktrunk.dev/hook/#pipeline-ordering) (blocks run in order, keys within a block run concurrently), and the approval model: user config is trusted; project config requires approval on first run. When both sources define the same name, both run — user first.
+Hooks and aliases share the TOML config file, the [template engine](https://worktrunk.dev/hook/#template-variables) (variables, filters, and functions), the [`[[block]]` pipeline syntax](https://worktrunk.dev/hook/#pipeline-ordering) (blocks run in order, keys within a block run concurrently), and the approval model: user config is trusted; project config requires approval on first run. When both sources define the same name, both run — user first.
## Hooks
@@ -101,7 +101,7 @@ wt config alias dry-run deploy -- --env=staging
### Multi-step pipelines
-`[[aliases.NAME]]` defines a pipeline using the same `[[block]]` [semantics as hooks](https://worktrunk.dev/hook/#pipeline-ordering) — blocks run in order, keys within a block run concurrently, a step failure aborts the remainder:
+`[[aliases.NAME]]` defines a pipeline using the [same `[[block]]` semantics as hooks](https://worktrunk.dev/hook/#pipeline-ordering) — blocks run in order, keys within a block run concurrently, a step failure aborts the remainder:
```toml
[[aliases.release]]
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index 82d0513ac..fae0ba441 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -106,8 +106,19 @@ static RUST_RAW_STRING_PATTERN: LazyLock<Regex> = LazyLock::new(|| {
/// Regex to convert Zola internal links to full URLs
/// Matches: [text](@/page.md) or [text](@/page.md#anchor)
+///
+/// Link text tolerates `]` characters when they appear inside a backticked
+/// code span (e.g. `[[block]]`), alternating "a `...` code span" with "any
+/// non-`]`-non-backtick char". Bare backticks are forbidden so the regex
+/// can't bridge across two unrelated code spans on the same line.
static ZOLA_LINK_PATTERN: LazyLock<Regex> =
- LazyLock::new(|| Regex::new(r"\[([^\]]+)\]\(@/([^)#]+)\.md(#[^)]*)?\)").unwrap());
+ LazyLock::new(|| Regex::new(r"\[((?:`[^`]*`|[^\]`])+)\]\(@/([^)#]+)\.md(#[^)]*)?\)").unwrap());
+
+/// Regex guardrail: any leftover `](@/...md...)` link that the transform
+/// above failed to rewrite. Used by the sync test to fail loudly on stray
+/// Zola internal links in generated skill content.
+static UNTRANSFORMED_ZOLA_LINK_PATTERN: LazyLock<Regex> =
+ LazyLock::new(|| Regex::new(r"\]\(@/[^)]+\.md").unwrap());
/// Regex to convert Zola rawcode shortcode to HTML pre tags
/// Matches: {% rawcode() %}...{% end %}
@@ -2180,6 +2191,22 @@ fn finalize_skill_content(content: &str) -> String {
})
.into_owned();
+ // Guardrail: ZOLA_LINK_PATTERN must catch every Zola internal link before
+ // we ship skill content. A stray `](@/...md...)` means the regex failed to
+ // match — usually because of unexpected chars in the link text — and the
+ // skill file would ship a dead link. Fail loudly instead.
+ if let Some(m) = UNTRANSFORMED_ZOLA_LINK_PATTERN.find(&content) {
+ let snippet_start = content[..m.start()].rfind('\n').map_or(0, |i| i + 1);
+ let snippet_end = content[m.end()..]
+ .find('\n')
+ .map_or(content.len(), |i| m.end() + i);
+ panic!(
+ "ZOLA_LINK_PATTERN failed to transform a Zola internal link in skill content — \
+ likely an unsupported character in the link text. Offending line:\n{}",
+ &content[snippet_start..snippet_end]
+ );
+ }
+
// Remove "See also" section (just contains links to other pages)
let content = remove_section(&content, "## See also");