Content organization

How docs, sections, and the sidebar tree fit together.

Docs are MDX files in the shared content package. A top-level folder is a section, docs by default, and the structure inside it becomes the sidebar:

• A file directly in the section is a standalone doc.
• A sub-folder becomes a group in the sidebar, with its pages nested underneath.
• weight in the front matter controls ordering.

Each page’s headings are collected automatically into its in-page table of contents, shown inline in the sidebar for the active page. No manual TOC needed.

The homepage

The landing page is content too: pages/home.mdx in the content package, rendered with the full shortcode set. Edit it like any other page; there is no need to touch the theme’s own templates to change your hero.

Landing pages

A group’s heading in the sidebar is a link, so every group needs a page behind it. You get one for free: Compose generates a landing page listing the group’s child pages, titled from the folder name. Add a folder, get a working group, with nothing to author and no dead link. The same holds for the section itself: /docs works whether or not you write it.

To write your own introduction, add an index.mdx inside the folder:

docs/
  index.mdx            <- the /docs landing page
  guide/
    index.mdx          <- the /docs/guide landing page
    installation.mdx
    configuration.mdx

---
title: Guide
weight: 5
description: Install Compose, configure it, and organize your content.
---

Its title names the group in the sidebar, overriding the folder name, and its body renders above the child list. The generated list stays, because it is navigation, not prose, so writing an introduction doesn’t cost you the index.

To take full control of the navigation, switch the list off and link the pages yourself:

---
title: Guide
listChildren: false
---

More than one section

Some sites need two documentation trees that don’t belong in one sidebar: a reference manual and a tutorial track, say. List them in docSections and each top-level folder mounts at its own segment:

export const config = defineThemeConfig({
  docSections: ["docs", "tutorials"],
});

packages/content/
  docs/         -> /docs
  tutorials/    -> /tutorials

Sections are independent tracks, not one site split in two. Each keeps its own sidebar, its own pager (which never walks from the end of one section into the start of another) and its own tags and categories, at /docs/tags/… and /tutorials/tags/…. Add a menu entry per section so both are reachable from the nav.