---
title: Folders and navigation
description: How the sidebar tree is derived from folder structure, how sections get titles, and how prev/next links are ordered.
order: 3
---

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

```markdown
---
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.