How Navigation Works

Compass keeps navigation explicit. Instead of inferring everything from folders, it combines your docs data file with article frontmatter and route templates.

The key files

• src/data/docs.ts defines parent sections, sub-categories, labels, descriptions, and slugs
• src/content/docs stores the articles and their frontmatter
• src/pages/[parent]/[category]/index.astro renders sub-category pages
• src/pages/[parent]/[category]/[slug].astro renders article pages
• src/components/Sidebar.astro renders the per-section sidebar

How article links are generated

Each article uses a category value in frontmatter. Compass matches that value to a category slug from src/data/docs.ts, then builds the URL from the category slug plus the article filename.

For example:

---
title: "Manage Docs"
category: "compass-docs"
---

Saved as manage-docs/manage-docs.mdx, this becomes /getting-started/compass-docs/manage-docs.

How the sidebar is assembled

Compass groups categories under parent sections. When a reader opens an article or category page, the sidebar is built from the categories that belong to that parent.

That means:

• top-level grouping comes from docsParentCategories
• section labels and slugs come from docsCategories
• article ordering inside a section comes from each article’s order frontmatter

Route structure

Compass uses nested article routes like /getting-started/compass-docs/manage-docs.

That structure matters because it:

• preserve the parent section in the URL
• keep breadcrumbs predictable
• make sidebar context clearer

When to update what

• change src/data/docs.ts when you want to rename or regroup sections
• change article frontmatter when you want to move or reorder a document
• add redirectFrom in article frontmatter when you want old paths to forward to the new canonical route
• change route templates only when the URL structure itself should change