Without a _toc.md, pages are listed in file-name order and titled by
their file name. That is fine for a handful of pages and wrong for almost
any real site — "Advanced" should not come before "Getting started" just
because A sorts first.
Add a file called _toc.md to the folder:
- [Welcome](welcome.md)
- [Getting started](getting-started.md)
- [Advanced usage](advanced.md)
Three things happen:
- Listed pages appear in the order you wrote them, in the sidebar and in prev/next links.
- The link text becomes the page's title in the navigation.
- Anything you did not list still appears, after the listed pages, in file-name order. Nothing disappears because you forgot it.
Shorter forms#
The link text is optional — a bare file name works and keeps the file's own name as the title:
- welcome.md
- getting-started.md
The .md extension is optional too, and matching ignores case. All four
of these find the same file:
- [Welcome](welcome.md)
- [Welcome](welcome)
- welcome.md
- Welcome.MD
Notes and headings are allowed#
Only lines that look like list items are read. Anything else is ignored, so you can keep the file readable:
# Navigation
Order matters here — reorder freely, nothing else needs updating.
- [Welcome](welcome.md)
- [Getting started](getting-started.md)
Tip
A file listed twice is used once, at its first position. A file that no longer exists is skipped silently, so a stale line will not break the site.