# 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.

- Canonical HTML: https://growth.iangoh.com/growth-ideas/markdown-file-links-for-version-safe-docs-navigation/
- Source: [docusaurus.io](https://docusaurus.io/docs/markdown-features/links)
- GrowthDex source hub: [Docusaurus Docs: Markdown links](/sources/docusaurus-docs-markdown-links-docusaurus-io/)
- Last checked: 2026-05-29
- Rarity: uncommon
- Budget: free
- Channels: Documentation, SEO, Developer Experience
- Stages: internal linking, docs ops, technical seo, developer docs


## Why this can grow

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.

## Ian's take

From scaling consumer platforms across MENA and Southeast Asia, my default is to distrust growth work that only looks good in a slide. For SEO and AI search, I care less about clever keyword tricks and more about clarity. A buyer, crawler, or answer engine should quickly understand who this is for, why it works, what proof backs it, and what page deserves to be cited. I would run it small enough to learn quickly, then only scale the parts that real users repeat, save, reply to, or buy from. For this tactic, I would watch one clear growth signal before putting more time or budget behind it.

## Action plan

1. Define one narrow startup segment where markdown file links for version-safe docs navigation can create a measurable lift.
2. Turn the tactic into one offer, page, campaign, or workflow for the Documentation and SEO channel.
3. Use the evidence from docusaurus.io to set the first version of the message, format, and audience.
4. Launch a small test for 7 to 14 days with one success metric: one measurable growth signal.
5. Review the result, keep the winning message, remove weak variants, and turn the learning into a repeatable growth playbook.

## Source-backed 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.

## Adjacent tactics in the same lane

- [Fail docs build on broken links before release](/growth-ideas/fail-docs-build-on-broken-links-before-release/) - 2 shared channels, 2 shared stages
- [Regex redirect families before docs group migration](/growth-ideas/regex-redirect-families-before-docs-group-migration/) - 2 shared channels, 2 shared stages
- [Promoted help articles for homepage first-click routing](/growth-ideas/promoted-help-articles-for-homepage-first-click-routing/) - 2 shared channels, 1 shared stage
- [Preview docs noindex before cutover](/growth-ideas/preview-docs-noindex-before-cutover/) - 2 shared channels, 1 shared stage

## Read GrowthDex essays

Browse the plain-English essay index at [GrowthDex Blog](/blog/).

## Related GrowthDex essays

- [The docs route should feel boring even when the product is moving](/blog/the-docs-route-should-feel-boring-even-when-the-product-is-moving/) - docs strategy, technical seo, support-led growth

## Advisory

If you want help turning this into a working growth system, Ian Goh offers advisory at https://iangoh.com/advisory.