Adding Docs Sections

This guide shows how to grow the documentation site without turning the config into a mess. The short version is simple: create the markdown pages first, then add the links and rewrites in .vitepress/config.mts.

The basic pattern

When you add a new docs area, keep the work in this order:

1. Create the markdown files in the right place.
2. Add a section entry to the sidebar.
3. Add a rewrite if the pages live inside a repo folder.
4. Link the new page from any overview or index page that should point to it.

That order keeps the site stable while you are still moving pages around.

Where to put the files

The documentation already uses two common patterns:

• Top-level pages live directly in the VitePress workspace, like getting-started/index.md or firmware/can-gateway.md.
• Repo-owned pages live inside the repo and are exposed through rewrites, like repos/CAN-Gateway/docs/modules/....

If the content belongs to one project, put it near that project. If it is a site-wide guide, keep it in the docs workspace.

Adding a new page

Create a markdown file with frontmatter and a clear title. A simple page usually looks like this:

---
title: New Section
description: Short one-sentence summary.
---

# New Section

Write the page in plain language. Explain what the section is for before listing details.

If the page belongs to a repo, keep the content near that repo and expose it through the VitePress rewrite map.

Adding it to the sidebar

The sidebar in .vitepress/config.mts is where the section becomes visible in the left navigation. Add the new page under the group that matches its topic.

Example for the Getting Started area:

{
  text: 'Getting Started',
  collapsed: true,
  items: [
    { text: 'Quick Start', link: '/getting-started/' },
    { text: 'Adding Docs Sections', link: '/getting-started/adding-docs-sections' },
    { text: 'Repo Map', link: '/overview/repo-map' }
  ]
}

If you add a new top-level docs area, mirror that pattern with a new sidebar group.

Adding rewrites for repo-local docs

When a page lives inside repos/..., add a rewrite so the URL stays clean. That keeps the public docs path tidy even though the source lives inside a repo folder.

Example rewrite:

rewrites: (page) => {
  if (page.startsWith('repos/CAN-Gateway/docs/')) {
    return page.replace('repos/CAN-Gateway/docs/', 'firmware/can-gateway/')
  }
  return page
}

The important part is consistency. If the file is stored in the repo, the sidebar link and the rewrite target should agree on the final public route.

Updating an existing section

If you are extending a section that already exists, make the smallest possible change:

• Add the new markdown page.
• Add the new sidebar link.
• Add or update the rewrite entry if needed.
• Add a link from the section index page so readers can discover the new page naturally.

That keeps the docs readable and avoids scattering the same page link across multiple places.

Good habits

TIP

Keep section names short and consistent. If one section says Data Processing, do not add another page called Processing of Data.

TIP

Prefer one clear purpose per page. If a section starts feeling too large, split it into a new page and link it from the index.

NOTE

For board-specific docs like CAN-Gateway, add the page where the code lives and keep the overview page focused on purpose and navigation.

Example checklist

Use this checklist when adding a new docs area:

• [ ] Create the markdown file.
• [ ] Add frontmatter with title and description.
• [ ] Add the page to the correct sidebar group.
• [ ] Add a rewrite if the file sits under repos/....
• [ ] Link the page from the relevant overview page.
• [ ] Keep the prose readable before adding any code snippets.

What to edit in config.mts

Most of the time you only need two sections in the config:

1. rewrites for repo-local content.
2. themeConfig.sidebar for navigation.

If you are adding a new repo-local page tree, update both together so the page can be reached from the sidebar and resolved by VitePress.