docref 0.1.0 (CLI + bundled extension), VS Code, Linux.
Setup: one VS Code workspace folder containing several sibling git repos, two of which have their own docref.toml at their repo root:
power-manage/ <- opened as the workspace folder (no docref.toml here)
docs/ docref.toml (declares cross-repo aliases server/agent/sdk)
sdk/ docref.toml (same-repo refs only)
server/ agent/ web/
The CLI, run from each repo root, is green in both repos. The extension, however, appears to resolve configuration and paths from the workspace folder instead of walking up from the file carrying the reference, producing two flavours of false error on every single reference:
- For
sdk/docs/** (same-repo refs), every ref reports broken with the workspace root in the message:
broken: pkg/dnf.go#dnf.Install (24ff67e3 -> ?) "pkg/dnf.go" not found in /home/…/power-manage
— the path is relative to sdk/, where the governing docref.toml lives.
- For
docs/content/** (aliased refs), every ref reports:
alias "server" is not declared in docref.toml; add it with: docref repo add server <url>
— the alias is declared, in docs/docref.toml; the extension seems to be reading a different (or no) config.
With ~500 refs across the two repos this yields 100+ error-severity squiggles on perfectly green docs, which trains users to ignore the diagnostics — the opposite of the tool's purpose. Expected: resolve each markdown file's governing docref.toml by walking up from that file (like ESLint/EditorConfig do), independent of the workspace folder, and scope alias resolution + relative paths to that root.
docref 0.1.0 (CLI + bundled extension), VS Code, Linux.
Setup: one VS Code workspace folder containing several sibling git repos, two of which have their own
docref.tomlat their repo root:The CLI, run from each repo root, is green in both repos. The extension, however, appears to resolve configuration and paths from the workspace folder instead of walking up from the file carrying the reference, producing two flavours of false error on every single reference:
sdk/docs/**(same-repo refs), every ref reports broken with the workspace root in the message:broken: pkg/dnf.go#dnf.Install (24ff67e3 -> ?) "pkg/dnf.go" not found in /home/…/power-manage— the path is relative to
sdk/, where the governing docref.toml lives.docs/content/**(aliased refs), every ref reports:alias "server" is not declared in docref.toml; add it with: docref repo add server <url>— the alias is declared, in
docs/docref.toml; the extension seems to be reading a different (or no) config.With ~500 refs across the two repos this yields 100+ error-severity squiggles on perfectly green docs, which trains users to ignore the diagnostics — the opposite of the tool's purpose. Expected: resolve each markdown file's governing
docref.tomlby walking up from that file (like ESLint/EditorConfig do), independent of the workspace folder, and scope alias resolution + relative paths to that root.