We propose adding a flexible multi-level directory structure to improve content organization and navigation for the documentation site.
Proposed Solution
Folder-as-a-Book approach, widely adopted by top documentation sites such as Vercel, Next.js, and Stripe Docs.
Core idea: use the file system hierarchy to reflect the logical structure of the docs.
- Each topic/series = a folder
- Overview page =
index.mdx inside the folder
- Child articles = other
.mdx files within the folder
- Use numeric prefixes (
01-, 02-) to define default ordering
Example Structure
content/
└── computer-science/
└── data-structures/
├── 01-introduction.mdx (standalone article)
├── array/ (series "Array")
│ ├── index.mdx (overview)
│ ├── 01-static-array.mdx
│ └── 02-dynamic-array.mdx
└── linked-list/ (series "Linked List")
├── index.mdx (overview)
├── 01-singly-linked-list.mdx
└── 02-doubly-linked-list.mdx
Benefits
- Highly intuitive: anyone opening the repo can instantly understand content structure.
- Clean, semantic URLs: automatically generate
/data-structures/linked-list and /data-structures/linked-list/singly-linked-list.
- Easy maintenance: related content lives together; adding, deleting, or editing is straightforward.
- Automatic navigation: sidebar navigation can be generated recursively, no manual config needed.
We propose adding a flexible multi-level directory structure to improve content organization and navigation for the documentation site.
Proposed Solution
Folder-as-a-Book approach, widely adopted by top documentation sites such as Vercel, Next.js, and Stripe Docs.
Core idea: use the file system hierarchy to reflect the logical structure of the docs.
index.mdxinside the folder.mdxfiles within the folder01-,02-) to define default orderingExample Structure
Benefits
/data-structures/linked-listand/data-structures/linked-list/singly-linked-list.