Skip to content

feat(docs): add flexible multi-level directory support #6

Description

@Crokily

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions