Compass
On this pageThe key files
  1. The key files
  2. How article links are generated
  3. How the sidebar is assembled
  4. Route structure
  5. When to update what

Compass Docs

How Navigation Works

Understand how Compass builds category pages, article links, and sidebar structure from your docs data.

2 min readUpdated
Compass Teampublishednavigationrouting

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/config/docs.ts defines parent sections, sub-categories, labels, descriptions, and slugs
  • src/content/docs stores the articles and their frontmatter
  • src/pages/[category]/index.astro renders parent landing pages such as /getting-started
  • src/pages/[parent]/[category]/index.astro renders sub-category pages
  • src/pages/[parent]/[category]/[slug].astro renders article pages
  • src/components/layout/DocsSidebar.astro renders the per-section sidebar with every article in that section
  • src/components/layout/TableOfContents.astro renders the “On this page” rail on wide screens
  • src/components/chrome/SiteHeader.astro renders a link per parent section, and a menu listing every category on smaller screens

How article links are generated

Each article uses a category value in frontmatter. Compass matches that value to a category slug from src/config/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
  • the current article and its category are highlighted as you move between pages

Route structure

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

That structure matters because it:

  • preserves the parent section in the URL
  • keeps breadcrumbs predictable
  • makes sidebar context clearer

Sub-category pages use the same nested shape. A category like compass-docs is available at /getting-started/compass-docs, not /compass-docs. Compass does not generate redirects for one-segment sub-category URLs by default.

When to update what

  • change src/config/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