How to Organize Your Documentation with Folders

Start with index.md

Every documentation site needs a root index.md. This becomes your homepage at /. Write a brief overview of what the documentation covers.

Use folders for sections

Group related pages into folders. Each folder becomes a section in the sidebar with the folder name as the heading (title-cased automatically).

docs/
├── index.md           → /
├── getting-started.md  → Getting Started
├── guides/             → GUIDES (section)
│   ├── installation.md →   Installation
│   └── deployment.md   →   Deployment
└── reference/          → REFERENCE (section)
    ├── api.md           →   Api
    └── cli.md           →   Cli

Use frontmatter for titles

File names are auto-title-cased (getting-started.md → "Getting Started"). Override with frontmatter for custom titles.

---
title: CLI Reference
order: 2
---

Control ordering

By default, items sort alphabetically. Use the order frontmatter field to control position. Lower numbers appear first. Items without order default to 999.

Add folder index pages

Add an index.md inside a folder to set the section title and order. The index content won't be rendered as a separate page — it sets metadata for the folder section.

Keep it shallow

Two levels of nesting is ideal. Three is fine. More than that makes the sidebar hard to scan. If you have deeply nested content, consider flattening your structure.