Organizing content

Good docs structure keeps pages easy to find. Treat folders as sections and meta.json files as the sidebar outline for each section.

Recommended shape#

This structure gives the docs enough breadth without making the starter feel empty.

src/content/docs/
  getting-started/
  writing-pages/
  organizing-content/
  customizing-ui/
  publishing/
  examples/
  reference/

Section overview#

Each folder should have an index.mdx page that introduces the section and links readers to the next task.

Child pages#

Child pages should cover one job each. Avoid combining setup, reference, and troubleshooting into one long page unless the workflow truly requires it.

Scaling the sidebar#

As docs grow, sidebar order becomes more important than file system order. Use metadata to keep the reading path intentional.

Reader mental model#

Beginner pages should appear before advanced customization. Reference pages should appear after the pages that teach the workflow.

Section boundaries#

Create a new section when a group of pages has its own audience, workflow, or maintenance owner. Avoid creating sections only because a sidebar feels visually balanced.

Workflow sections#

Workflow sections teach a sequence of tasks. They usually start with an overview, continue with setup or writing pages, and end with review notes.

Reference sections#

Reference sections help readers look up details after they already understand the workflow. These pages can be denser but still need clear headings.

Growth signals#

Docs structure should evolve when pages become hard to scan. Watch for signs that one page or one section is carrying too much responsibility.

Split long pages#

Split a page when its table of contents contains unrelated tasks. A long page is fine when it follows one workflow, but not when it combines many jobs.