Unlinked Internal Reference¶
Rule ID: content-unlinked-internal-reference
Detect bare path-like strings not wrapped in markdown link syntax
| Severity | info (auto) |
| Autofix | auto |
| Since | v0.9.0 |
Configuration¶
| Parameter | Description | Default |
|---|---|---|
patterns |
Glob patterns for path-like strings to flag when unlinked | ["./**/*.*", "references/**/*.md"] |
Research Basis¶
Detects bare path-like strings that are not wrapped in markdown link syntax
(e.g., src/config.yaml mentioned in prose but not linked as
[src/config.yaml](src/config.yaml)).
Bare path references are a maintenance hazard. When a path is mentioned in
prose without link syntax, there is no tooling (including
content-broken-internal-reference) that can verify the referenced file still
exists. The path silently rots as the repository evolves.
Wrapping paths in link syntax provides two benefits: (1) link checkers and linters can detect when the target is renamed or deleted, and (2) in rendered markdown environments (GitHub, IDEs), the reference becomes navigable. Both benefits improve the reliability of instruction files as executable context.
The rule is configurable via patterns — a list of glob patterns that control
which path-like strings are flagged. This avoids false positives on paths that
are illustrative examples rather than real file references.
References:
- Google Technical Writing: Links — "Use meaningful link text" — paths mentioned without links are un-navigable and un-verifiable
- Microsoft Writing Style Guide: Links — Bare URLs and paths should be formatted as actionable links