Folders and navigation

Your folders and page front matter define the sidebar. You do not need a separate navigation file.

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 root index.md appears in the sidebar. Set its title to the label you want readers to see.

Sections without a landing page

A folder without index.md appears as a section heading without a link.

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.

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

Nested paths such as a/b/c/d.md are supported. For a sidebar readers can scan easily, keep the structure shallow and split deep trees into separate sections.

Previous and next

Previous and next links follow sidebar order, skipping section headings that have no landing page.

When the tree rebuilds

Navigation updates automatically after page imports, edits, deletions, and completed rerenders. No separate publish call is needed; cached pages can take time to reflect the change.