EditMD
Edit on GitHubLink to Markdown

astro-better-docs-sidebar

Builds a sidebar navigation tree from an Astro content collection. Handles nested directories, folder expansion, active-page highlighting, and order / hidden frontmatter fields.

Current version: 0.2.0 --npm

Installation

$ npm install astro-better-docs-sidebar

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="/docs"
/>

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.

Props

PropTypeDefaultDescription
frontmatterRecord<string, any>(required)Current page frontmatter (used for active detection)
collectionCollectionEntry[](required)The full content collection array
basePathstring(required)URL prefix for all sidebar links
folderBehavior'page' | 'unclickable' | 'overview''page'How folder nodes behave
overviewLabelstring'Overview'Label for the auto-generated overview link when folderBehavior='overview'

Frontmatter fields

FieldTypeDescription
titlestringItem label in the sidebar
ordernumberSort order (lower numbers first)
hiddenbooleanHide this page from the sidebar
routebooleanSet to false on a folder’s index.mdx to prevent the sidebar from linking to it
sidebar.labelstringOverride the sidebar label (without changing the page title)
sidebar.folderBehaviorstringOverride folder behavior for this specific folder

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 directly
  • unclickable: the folder node is a label with no link; only children are clickable
  • overview: an “Overview” link is auto-generated as the first child
Requires Tailwind

The sidebar uses Tailwind @apply in its &lt;style&gt; block, so Tailwind must be installed in the consuming project. All classes use the .dark variant for dark mode.