Sidebar

The sidebar is driven by content/_nav.mdx — a special infrastructure file that defines navigation sections using a family of directives. At build time, src/lib/nav.ts parses this file and passes the result to the <Sidebar> client component via the server layout.

The _nav.mdx file

content/_nav.mdx lives in the content/ directory with a _ prefix so it is excluded from all content pipelines — it has no public URL and never appears in article listings.

Each section is declared with a :::nav-section container directive. Inside it, ::nav-item and ::nav-dir child directives specify the links. Every opening line and the last line before the closing ::: must end with two trailing spaces so Prettier does not collapse them (see the container directive formatting rules).

---
title: Navigation
---
 
:::nav-section{label="Getting Started"}  
::nav-item{href=/ title=Overview}  
:::
 
:::nav-section{label="Guides"}  
::nav-dir{dir=guides}  
:::
 
:::nav-section{label="Reference"}  
::nav-dir{dir=reference}  
:::
 
:::nav-section{label="Directives" type=directive}  
::nav-dir{dir=directives}  
:::

Sections are rendered in the order they appear in the file.

:::nav-section

Container directive. Defines one group in the sidebar.

:::nav-section{label="Section Name" type=directive}  
...child directives...  
:::

::nav-item

Leaf directive. Adds a single fixed link to the enclosing section.

::nav-item{href=/some/path title="Page Title"}

::nav-dir

Leaf directive. Populates the enclosing section with all non-draft articles from a content directory, sorted by publish-date (newest first, then alphabetically).

::nav-dir{dir=guides}

Any .mdx file added to content/<dir>/ automatically appears in the sidebar on the next build — no changes to _nav.mdx needed.

Directive-style sections

type=directive on :::nav-section renders each item with a :: monospace prefix. Use this for sections that list directives so the naming convention is visually reinforced.

:::nav-section{label="Directives" type=directive}  
::nav-dir{dir=directives}  
:::

Mixing item types

A single section can contain both ::nav-item and ::nav-dir — items are added in the order the child directives appear:

:::nav-section{label="Start Here"}  
::nav-item{href=/ title=Overview}  
::nav-dir{dir=guides}  
:::

Adding a new section

Add a :::nav-section block to content/_nav.mdx:

:::nav-section{label="Blog"}  
::nav-dir{dir=blog}  
:::

Then create content/blog/ and populate it with .mdx files. The sidebar reflects the change on the next build.

Removing a section

Delete the corresponding :::nav-section block from content/_nav.mdx. The content files are unaffected and remain routable — they just no longer appear in the sidebar.