Links in Content

To link to another page in your content, write its file path:

Start with [Getting Started](../getting-started.mdx).

See [the document tree](../concepts/document-tree.mdx#four-functions) for groups.

At build time, minidocs replaces it with the page’s URL. It is how you write links when browsing Markdown on GitHub or in an editor, so your editor can complete paths and jump to files. Changing settings such as prefix or base leaves the links as they are.

A link to a file that does not exist fails the build:

[minidocs] src/content/docs/en/guides/sidebar.mdx:12: "../getting-started.md" points to a file that does not exist.

Rules

Only relative paths ending in .md or .mdx are rewritten, and the extension is required. External links, URLs starting with / and #anchors stay as they are
Anchors are kept: ../install.mdx#requirements links to #requirements on that page
Links can point into another collection loaded with minidocs’ glob, see Multiple Collections
A link to a file outside those collections, such as README.md at the project root, fails the build, since it has no page
A link to a page that filter leaves out also fails the build

Multilingual sites

A link to a file in the same locale directory links to the page in the same locale.

When a page is not translated and shows content from another locale, its links still point to pages in the current locale, so readers are not taken to the other locale’s site.

To link to another locale on purpose, write the file in that locale’s directory:

<!-- en/guides/deploy.mdx -->
This section is only in Chinese: [部署](../../zh/guides/deploy.mdx).

Limitations

Anchors come from heading text. An English page linking to #four-functions may land on a page that is shown in Chinese through fallback, where the heading is #四个函数, and the link only reaches the top of the page
Links are relative URLs. When you use the rendered HTML elsewhere, such as the full text in an RSS feed, turn them into full URLs yourself
In the dev server, a broken link only reports an error when you open its page, and broken links in .md files only show in the terminal. Builds fail on both