Build a Documentation Site with Collections and MDX
How Aveiro's file tree, collection layouts, and MDX conventions map to real docs architecture — URL segments, sidebar nav, manual sort, and Collection blocks.
Pick a docs template, organize pages into collections (folders), set layout and sort at the collection level, then use MDX for callouts and tables. The public sidebar mirrors manual tree order — plan structure before you publish deep hierarchies.
Who this is for
You already know what a documentation site needs: grouped guides, predictable URLs, a sidebar that matches how readers think, and occasional rich blocks (callouts, tables, CTAs) without leaving the editor.This guide is for teams building product docs, internal handbooks, or multi-chapter guides on Aveiro — not a generic “how to write Markdown” tutorial. It focuses on the mechanics that only show up when structure matters.If you are publishing a single landing page, skip to Your first week on Aveiro. If you are planning /guides/quickstart beside /api/authentication, read on.
Start from a docs-shaped template
Templates encode layout assumptions — sidebar width, collection index behavior, typography for long reads.
Create a site from a docs or documentation-style template (see Choosing a template).
Open the file tree in the editor and inspect the starter folders — they are collections, not decorative grouping.
Rename collections for URL segments early. Changing a segment later breaks external links.
The file tree is the source of truth for both routing and, on docs templates, left navigation order.
Updated by Quasar 13 days ago
