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.
Open a collection’s Settings before you add dozens of pages:
Setting
Why it matters
Collection name
Label in the tree and sidebar
URL segment
Path prefix for every child page
Page layout
Layout template child pages inherit
Page order
Sort mode override for pages in this folder
Default at collection, override at page keeps maintenance sane. Only open page-level layout overrides when a single chapter needs a different shell (e.g. a full-width diagram page).
Docs templates expose collection layouts — sidebar + content column, optional collection index, and nav chrome. See Collection layouts for how inheritance works.
Manual sort is a feature, not a chore
Alphabetical order is fine for glossaries. Documentation almost never wants it.
Set Page order → Manual on the collection (or site root when the template reads tree order globally).
Drag pages in the file tree to match the learning path — onboarding before advanced topics.
Publish page content after reordering; nav on the live site follows the tree when the template exposes sidebar navigation.
On docs-style sites, the sidebar is the syllabus. Treat reordering as curriculum design, not file housekeeping.
Nesting: how deep is too deep?
You can nest collections for deep hierarchies (/guides/api/auth/oauth). Practical limits:
Two levels — comfortable for most product docs.
Three levels — acceptable for large platforms; test mobile nav early.
Four or more — readers get lost; consider flattening with better index pages.
Each nested collection gets its own URL segment. Plan paths before writers link to them from GitHub issues or in-app help.
Collection blocks for auto-index pages
Not every section needs a hand-maintained list of links. MDX Collection components list pages from a folder (or the whole site) and respect the same manual sort order as the file tree.
Use them for:
A /guides hub that always reflects the latest chapter list
Card grids on overview pages
“Related guides” sections scoped to one folder
They read from the same ordering you configured in the tree — no duplicate sort lists to maintain.
MDX conventions that survive a team
Most edits happen in Visual mode. Source mode matters when you need precise control — custom sections, registered components, or bulk find-and-replace across pages.
Rules that keep docs maintainable:
Do
Avoid
Use registered components from the catalog
Raw HTML layout tags for structure
Table component with headers and rows props
Pipe Markdown tables (not rendered in Aveiro MDX today)
Page title and summary in Page settings
YAML frontmatter for SEO metadata
Feedback blocks for warnings and tips
Long italic asides that break scanability
lowercase_with_underscores for analytics event names
Renaming events after launch without checking Analytics → Events
