Navigation Sidebar
On this page
Builds a sidebar navigation tree from an Astro content collection. Handles nested directories,
folder expansion, active-page highlighting, overview pages, and order / hidden frontmatter fields. Requires Tailwind CSS.
The tree is built and sorted once per collection and reused across pages, so large docs sites don’t rebuild it for every page they render.
Installation
$ npm install astro-better-docs-sidebar
Folder behavior modes
folderBehavior controls what happens when a folder has an index.md(x) file:
page(default): the folder node links to the index page directlyunclickable: the folder node is a label with no link; only children are clickableoverview: an “Overview” link is auto-generated as the first child
Style the sidebar container
The sidebar requires Tailwind for its internal <style> block.
Wrap it in an <aside> with the aside class, or let it render inline.
Setup
Define your content collection
In src/content/config.ts, include order, hidden, and sidebar fields:
import { defineCollection, z } from 'astro:content';
const docs = defineCollection({
type: 'content',
schema: z.object({
title: z.string(),
order: z.number().optional(),
hidden: z.boolean().optional(),
route: z.boolean().optional(),
sidebar: z.object({
label: z.string().optional(),
folderBehavior: z.enum(['page', 'unclickable', 'overview']).optional(),
}).optional(),
}),
});
export const collections = { docs };
Add the Sidebar to your layout
---
import Sidebar from 'astro-better-docs-sidebar/Sidebar.astro';
import { getCollection } from 'astro:content';
const docsCollection = await getCollection('docs');
---
<Sidebar
frontmatter={Astro.props}
collection={docsCollection}
basePath="/"
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
frontmatter | Record<string, any> | (required) | Current page frontmatter (used for active detection) |
collection | CollectionEntry[] | (required) | The full content collection array |
basePath | string | (required) | URL prefix for all sidebar links |
folderBehavior | 'page' | 'unclickable' | 'overview' | 'page' | How folder nodes behave |
overviewLabel | string | 'Overview' | Label for the auto-generated overview link when folderBehavior='overview' |
Frontmatter fields
| Field | Type | Description |
|---|---|---|
title | string | Item label in the sidebar |
order | number | Sort order (lower numbers first) |
hidden | boolean | Hide this page from the sidebar |
route | boolean | Set to false on a folder’s index.mdx to prevent the sidebar from linking to it |
sidebar.label | string | Override the sidebar label (without changing the page title) |
sidebar.folderBehavior | string | Override folder behavior for this specific folder |