Folders

Folders create sections in the docs. A folder can contain an overview page, child pages, and metadata for sidebar order.

Section folder#

A section folder groups related pages and gives the sidebar a stable structure.

writing-pages/
  index.mdx
  frontmatter.mdx
  mdx-basics.mdx
  images.mdx
  meta.json

Overview page#

The index.mdx page explains what the section covers. It should not duplicate every child page, but it should help readers choose where to go next.

Child pages#

Child pages should be small enough to maintain but complete enough to solve a task. Split pages when the table of contents becomes too broad.

Folder rules#

Apply these rules when creating new sections or renaming existing pages.

• Use lowercase slugs.
• Prefer hyphens between words.
• Add an index.mdx page for section overviews.
• Keep related pages together instead of scattering them across sections.

Naming rule#

Use names that describe the public URL. A good slug should still make sense if someone shares the link in chat.

Folder depth#

Keep folder depth shallow until the content truly needs another layer. Deep nesting makes URLs longer and makes sidebar behavior harder to predict.

One level first#

Start with one folder per section and one file per page. This is enough for most documentation starters and product docs.

Nested sections later#

Add nested folders when a section has multiple groups of child pages that need their own overview pages.

Migration tips#

Rename folders carefully because folder names usually become public URLs. Plan redirects or update links when changing a published slug.

Move in small batches#

Move one section at a time and review links after each batch. This makes broken paths easier to catch.