When a Category Is Just a Flat List

Jan 28, 2026

A category index can stay simple when every child belongs to the same small collection.

Structure should match the content

Not every category needs another layer of folders. Getting Started is a short sequence of independent pages, so its index is easier to scan when it presents a numbered list. The files stay beside one another, and their sidebar_position values express the order without introducing an artificial hierarchy.

The navigation guide still recommends directories as the source of sidebar structure. A note tray follows that principle: the directory is the category, while the category's declaration chooses a flat presentation for its direct children.

A useful constraint

Keeping the list flat also makes the writing task clearer. Each page needs a useful title, a deliberate rank, and a description that works in a compact index. If the list starts mixing unrelated topics or needs more than a quick scan, that is a signal to create a new category rather than add more decoration.