Folders and navigation

There is no navigation config file. No SUMMARY.md, no sidebar.json, no ordering manifest. The sidebar is derived from the page paths and their order front matter, and it is rebuilt on every write.

The mapping

A folder is a section. A page whose path equals the folder path is that section's landing page.

docs/
  index.md                 →  /                    top-level entry
  quickstart.md            →  /quickstart          top-level entry
  guide/
    index.md               →  /guide               section landing page
    install.md             →  /guide/install       inside the section
    configure.md           →  /guide/configure     inside the section

That produces:

• Home (from index.md, linking to /)
• Quickstart
• Guide — a clickable section heading, with Install and Configure nested beneath it

The version root page — index.md at the top of the folder — is a normal top-level sidebar entry, not a hidden home link. Give it a title you are happy to see in the sidebar.

Sections without a landing page

If a folder contains pages but no index.md, Docsary synthesizes a section node for it. The synthesized section is a heading only. It is never a link, because there is no page to link to.

Its title is derived from the folder name: hyphens and underscores become spaces, and each word is capitalized. getting-started/ becomes Getting Started. Its sort order is always 0.

To control either, add an index.md to the folder:

---
title: Getting started
order: 1
---

# Getting started

Three things to do first.

That gives the section a real title, a real position, and a page of its own.

Ordering

Entries in a section sort by order ascending, then by title alphabetically when orders tie. The default order is 0, so a folder in which nothing declares an order is alphabetical.

Ordering is scoped to a section. A section's own order — taken from its index.md — places it among its siblings. The order values inside it place its children among each other. There is no global ordering number.

Leaving gaps between numbers (10, 20, 30) makes inserting a page later a one-line change. Negative numbers work and sort first.

Depth

Nesting is not limited by the data model — a/b/c/d.md is a valid path. The sidebar styles the first two levels distinctly: top-level entries with children render as section headings, and deeper levels render as an indented list with a left rule. Beyond three levels the sidebar becomes hard to scan. Prefer splitting a deep tree into more top-level sections.

Previous and next

The prev/next links at the foot of each page walk a flattened version of the sidebar in display order. Synthesized sections are skipped, because they have no page to land on. A section with a landing page is a stop in the sequence.

The order you see in the sidebar is exactly the order the prev/next links follow. Fixing one fixes the other.

When the tree rebuilds

The navigation tree is recomputed and stored whenever pages change: after an import, after a single-page PUT or DELETE, and at the end of a full rerender. You do not rebuild it by hand, and there is no separate publish step needed to make a navigation change visible.

A navigation change shows up on every page of the site at once — moving a page in the sidebar never leaves half the site pointing at the old arrangement.