Docs Module

The docs module publishes documentation pages with left-sidebar navigation. Each docs section gets its own mount path, collection, and sidebar.

Adding the docs module

In karaoke.config.ts:

import { defineConfig } from '@karaoke-cms/astro';
import { docs } from '@karaoke-cms/module-docs';
import { themeDefault } from '@karaoke-cms/theme-default';

export default defineConfig({
  vault: env.KARAOKE_VAULT,
  title: 'My Site',
  theme: themeDefault(),
  modules: [
    docs(),
  ],
});

This creates a docs section at /docs, reading files from the docs/ folder in your vault.

Options

Option	Default	Description
mount	/docs	URL prefix for all routes in this section
folder	mount without /	Vault subfolder containing the markdown files
id	folder with slashes replaced by hyphens	Astro collection name — must be unique across all docs instances
label	id in Title Case	Navigation label and page heading
enabled	true	Set false to exclude from the build
comments	false	Default comments visibility for all pages in this section
sidebarStyle	'tree'	Sidebar rendering style
layout	'default'	Page layout override

docs({
  mount: '/docs',
  folder: 'docs',
  label: 'Documentation',
  comments: false,
  enabled: true,
})

Routes injected

Route	Description
/docs	Section home — lists all doc titles
/docs/list	Full standalone docs list
/docs/[slug]	Individual doc page with sidebar

Writing docs pages

Create .md files in your vault’s docs/ folder (or whichever folder the section is configured to read from).

---
title: "Getting Started"
publish: true
description: "How to install and configure the project."
weight: 1
---

Page content here.

publish: true is required. Pages without it are excluded from the build.

Frontmatter fields

Field	Description
title	Required. Displayed in the sidebar and as the page heading
publish	Required. Must be true for the page to appear on the site
description	Summary for SEO meta tags
weight	Controls sidebar order — lower weight appears higher

Sidebar ordering

The sidebar lists all pages in the section ordered by weight. Pages with no weight set are sorted after weighted pages, alphabetically.

# This page appears first in the sidebar
weight: 1

# This page appears second
weight: 2

Pages without a weight field are sorted alphabetically after all weighted pages.

Comments

Comments are off by default for docs sections. To enable comments on a specific page, add comments: true to its frontmatter:

---
title: "Feedback Welcome"
publish: true
comments: true
---

To enable comments on all pages in a section by default:

docs({ comments: true })

Multiple docs sections

You can add more than one docs section — for example, a main docs area and a separate API reference. See multiple-docs-sections for the full guide.