flo-bit.dev
[READ-ONLY] Mirror of https://github.com/flo-bit/tiny-docs. quick setup, simple, minimalistic docs for your github project
flo-bit.dev/tiny-docs/
1# Internal links
2
3Links between your markdown files need to match how tiny-docs builds URLs, or they'll 404 in the deployed site.
4
5## The rules
6
7- Write links to the **actual file path**, with the `.md` (or `.mdx`) extension.
8- Paths may be relative (`./foo.md`, `../bar.md`) or absolute from the repo root (`/docs/foo.md`).
9- Numeric prefixes (`01-`, `02-`) are stripped from the URL but must stay in the link.
10- All URLs are lowercased.
11- `README.md` maps to `/`.
12
13## Examples
14
15Given this layout:
16
17```
18README.md
19docs/
20 01-getting-started.md
21 guide/
22 01-install.md
23 02-usage.md
24```
25
26From `docs/guide/01-install.md`:
27
28```md
29[Getting started](../01-getting-started.md) → /docs/getting-started
30[Usage](./02-usage.md) → /docs/guide/usage
31[Home](/README.md) → /
32```
33
34## Common pitfalls
35
36- **Don't omit the extension.** `[link](../getting-started)` won't resolve — write `[link](../getting-started.md)`.
37- **Don't hand-craft the final URL.** Writing `[link](/docs/guide/usage)` skips the rewriter and breaks when `BASE` is set (project pages served under `/<repo>/`). Link to the file.
38- **Anchors work normally.** `[section](./usage.md#install)` is fine.
39- **External links** (starting with `http`) are left untouched and open in a new tab.