Markdown file links for version-safe docs navigation
Link docs to each other with file-path references instead of hand-typed relative URLs so route changes do not quietly rot the graph.
Why this can grow a startup
Documentation links fail in boring ways. Someone changes a slug, moves a file, or updates a trailing-slash rule, and the help center still looks fine until users hit the stale path. Docusaurus recommends linking docs by relative file paths with `.md` extensions because those links survive file moves, respect per-version routing, and are far less likely to break when route settings change. The gain is partly technical, but it is mostly operational. Editors can rename or reorganize pages without turning the internal link graph into a scavenger hunt.
Company example
Docusaurus says file-path links keep working across editors, follow the exact same version in versioned docs, and are less likely to break when the `trailingSlash` config changes.
Source and metric
Source: Docusaurus Docs: Markdown links
Docusaurus notes that file-path links preserve version-aware navigation, while relative URL links are very likely to break if `trailingSlash` changes.
Source discovered: May 29, 2026
When to use it
Use this when Documentation, SEO, Developer Experience is relevant to internal linking, docs ops, technical seo and you can run a bounded test with a free budget.
When not to use it
Do not use it as a substitute for customer evidence, a clear owner, or a measurable stop condition. Local platform rules and market behavior still need checking.
Founder checklist
- Read Docusaurus Docs: Markdown links and identify what is directly supported.
- Choose one channel context: Documentation, SEO, Developer Experience.
- Define the test around Docusaurus notes that file-path links preserve version-aware navigation, while relative URL links are very likely to break if `trailingSlash` changes..
- Set an owner, evidence window, and stop condition before launch.
Explore the context
Apply this with an operator
Turn isolated search tactics into a crawlable visibility system tied to demand and proof.