Compass
On this pageTheme structure
  1. Theme structure
  2. How content is grouped
  3. Where navigation comes from
  4. Where article metadata comes from
  5. How the pages connect

Start Here

How Compass Is Organized

Understand how Compass is structured so you know where to customize content, navigation, and layout.

2 min readUpdated

Compass is a docs theme built around a small set of moving parts. Once you know where each part lives, the project becomes much easier to customize.

Theme structure

The theme is organized into a few main areas:

  • src/pages controls routes
  • src/layouts wraps page structure
  • src/components contains the header and footer, homepage sections, docs navigation, and MDX components
  • src/content/docs stores article content
  • src/config holds the settings: site.ts for the site, docs.ts for the docs structure, and home.ts for the homepage
  • src/lib/docs.ts holds the helpers that sort, filter, and link articles
  • src/styles/global.css holds the design tokens and styles

How content is grouped

Compass uses a three-level model:

  1. Parent categories such as Getting Started or Integrations
  2. Sub-categories such as Compass Docs or Start Here
  3. Individual articles inside those sub-categories

This structure powers:

  • the homepage sections and cards
  • the header links and mobile menu
  • the left sidebar on docs pages
  • the category labels in search results

Where navigation comes from

The docs navigation is not inferred only from folders. It is primarily defined in src/config/docs.ts, which gives you explicit control over:

  • labels
  • slugs
  • parent grouping
  • card descriptions
  • icons for the homepage cards, the sidebar, and the mobile menu

Where article metadata comes from

Each article in src/content/docs uses frontmatter like this:

---
title: 'Manage Docs'
description: 'Update structure, copy, and article metadata across your Compass docs.'
category: 'compass-docs'
order: 2
updatedAt: 2026-06-03
---

The category value links an article to one of the sub-categories declared in src/config/docs.ts.

How the pages connect

  • / renders the homepage sections and cards
  • /:parent renders a parent landing page such as getting-started
  • /:parent/:category renders a sub-category page such as getting-started/compass-docs
  • /:parent/:category/:slug renders the individual article

Compass does not generate one-segment sub-category pages such as /compass-docs or /start-here. The nested parent/category path is the only built-in category URL.

Once this model makes sense, you can start swapping in your own structure without fighting the theme. For a deeper route-specific walkthrough, see How Navigation Works.