Configuration Reference

defineConfig()

Defined in @karaoke-cms/astro. Import:

import { defineConfig } from '@karaoke-cms/astro';

KaraokeConfig type

interface KaraokeConfig {
  vault?:       string;
  title?:       string;
  description?: string;
  theme?:       string | ThemeInstance;
  modules?:     (ModuleInstance | ModuleInstance[])[];
  collections?: Record<string, CollectionConfig>;
  comments?:    CommentsConfig;
  layout?: {
    regions?: {
      top?:    { components?: RegionComponent[] };
      left?:   { components?: RegionComponent[] };
      right?:  { components?: RegionComponent[] };
      bottom?: { components?: RegionComponent[] };
    };
  };
}

Top-level options

Name	Type	Required	Default	Description
`vault`	`string`	No	project root	Path to the Obsidian vault root. Absolute or relative to the Astro project root. Set via `KARAOKE_VAULT` in `.env.default`.
`title`	`string`	No	`'Karaoke'`	Site title — shown in browser tab and nav bar.
`description`	`string`	No	—	Site description — used in RSS feed and OG meta tags.
`theme`	`string \| ThemeInstance`	Yes	—	Theme instance from `defineTheme()`. Pass `themeDefault()`, `themeMinimal()`, etc.
`modules`	`(ModuleInstance \| ModuleInstance[])[]`	No	`[]`	Modules to activate. `karaoke()` flattens nested arrays automatically.
`collections`	`Record<string, CollectionConfig>`	No	—	Per-collection mode and label overrides. Merges with built-in defaults; this field takes precedence.
`comments`	`CommentsConfig`	No	—	Giscus configuration. Also used by `comments()` module.
`layout`	`object`	No	—	Layout region component placement.

CollectionConfig type

interface CollectionConfig {
  modes?: ('dev' | 'prod')[];
  label?: string;
}

CommentsConfig type

interface CommentsConfig {
  enabled?:    boolean;
  repo?:       string;   // "owner/repo"
  repoId?:     string;
  category?:   string;
  categoryId?: string;
}

blog()

Package: @karaoke-cms/module-blog

import { blog } from '@karaoke-cms/module-blog';

blog(config?: BlogConfig): ModuleInstance

BlogConfig options

Name	Type	Default	Description
`mount`	`string`	`''` (root)	URL prefix for all blog routes.
`id`	`string`	`'blog'`	Module identifier. Rarely needs changing.
`enabled`	`boolean`	`true`	When `false`, routes and menu entries are not injected.
`comments`	`boolean`	`true`	Default comments visibility for all posts. Overridable per-post via frontmatter.

Routes injected

Pattern	Description
`{mount}`	Post list (page 1)
`{mount}/[slug]`	Individual post
`{mount}/page/[page]`	Paginated list

Section	Entry	Weight
`main`	Blog → `{mount}`	10
`footer`	RSS → `/rss.xml`	10

docs()

Package: @karaoke-cms/module-docs

Two call signatures:

import { docs } from '@karaoke-cms/module-docs';

// Single section
docs(config?: DocsConfig): ModuleInstance

// Multiple sections
docs(sections: DocsSection[]): ModuleInstance[]

DocsConfig options (single-section form)

Name	Type	Default	Description
`mount`	`string`	`'/docs'`	URL prefix for this docs section.
`folder`	`string`	mount without leading `/`	Vault subfolder containing markdown files.
`id`	`string`	folder with `/` → `-`	Astro collection name. Must be unique across all docs instances.
`label`	`string`	id in Title Case	Nav label and page heading.
`enabled`	`boolean`	`true`	When `false`, excluded from build.
`comments`	`boolean`	`false`	Default comments visibility for pages in this section. Overridable per-page via frontmatter.
`layout`	`string`	`'default'`	Layout component override.
`sidebarStyle`	`string`	`'tree'`	Sidebar style: `'flat'` or `'grouped'`.

DocsSection fields (array form)

Each element of the DocsSection[] array has the same fields as DocsConfig plus:

Name	Type	Default	Description
`weight`	`number`	`20`	Menu weight for ordering. Blog = 10, Tags = 30. Use 11–29 to appear between them.
`parent`	`string`	—	Id of a root-level nav entry to nest this section under. Single-level only. Falls back to root if not found.

Routes injected (per instance, via codegen)

Pattern	Description
`{mount}`	Docs home — list of all doc titles
`{mount}/list`	Full docs list page
`{mount}/[slug]`	Individual doc page with sidebar

Section	Entry	Weight
`main`	`{label}` → `{mount}`	`weight` (default 20)

tags()

Package: @karaoke-cms/module-tags

import { tags } from '@karaoke-cms/module-tags';

tags(config?: TagsConfig): ModuleInstance

TagsConfig options

Name	Type	Default	Description
`mount`	`string`	`'/tags'`	URL prefix for tags routes. Cannot be `'/'` or empty.
`enabled`	`boolean`	`true`	When `false`, routes are not injected.

Routes injected

Pattern	Description
`{mount}`	All-tags index
`{mount}/[tag]`	Per-tag post list
`{mount}/[tag]/rss.xml`	Per-tag RSS feed

Section	Entry	Weight
`main`	Tags → `{mount}`	30

search()

Package: @karaoke-cms/module-search

import { search } from '@karaoke-cms/module-search';

search(config?: { mount?: string; enabled?: boolean }): ModuleInstance

Options

Name	Type	Default	Description
`mount`	`string`	`'/search'`	URL for the search page.
`enabled`	`boolean`	`true`	When `false`, routes are not injected.

Routes injected

Pattern	Description
`{mount}`	Full-text search page (Pagefind)

Section	Entry	Weight
`main`	Search → `{mount}`	90

Notes

Runs pagefind on the built dist/ directory after astro:build:done. In dev mode, serves the pre-built Pagefind index from dist/pagefind/ — run pnpm build once first to generate the index.

comments()

Package: @karaoke-cms/module-comments

import { comments } from '@karaoke-cms/module-comments';

comments(config: CommentsConfig): ModuleInstance

CommentsConfig options

Name	Type	Required	Default	Description
`repo`	`string`	Yes	—	GitHub repo in `"owner/repo"` format. Must have Discussions enabled.
`repoId`	`string`	Yes	—	GitHub repo ID from giscus.app.
`category`	`string`	No	`'General'`	GitHub Discussions category name.
`categoryId`	`string`	No	`''`	GitHub Discussions category ID from giscus.app.
`enabled`	`boolean`	No	`true`	When `false`, module is excluded from the build.

Routes injected

None. The Giscus widget is embedded by the theme on individual post/doc pages.

None.

seo()

Package: @karaoke-cms/module-seo

import { seo } from '@karaoke-cms/module-seo';

seo(config?: SeoConfig): ModuleInstance

SeoConfig options

Name	Type	Default	Description
`disallow`	`string[]`	`['/karaoke-cms/']`	URL paths to block in `robots.txt`.
`llmsTxt`	`boolean`	`true` (when `site` is set)	When `false`, skip `/llms.txt`.
`llmsSiteTitle`	`string`	hostname	`#` title in `llms.txt`.
`llmsTxtExtra`	`string`	—	Extra Markdown appended to `llms.txt`.
`contentManifest`	`boolean`	`true` (when `site` is set)	When `false`, skip `karaoke-public-content.json`.

Routes injected

None. Runs at astro:build:done to generate OG images, JSON-LD, robots.txt, optional llms.txt, and optional karaoke-public-content.json.

None.

Layout regions

Place built-in UI components into layout regions via karaoke.config.ts:

layout: {
  regions: {
    right: { components: ['recent-posts'] },
    top:   { components: ['header', 'main-menu'] },
  },
},

RegionComponent values

Value	Description
`'header'`	Site header with title
`'main-menu'`	Primary navigation menu
`'search'`	Search input
`'recent-posts'`	Recent posts sidebar widget
`'footer'`	Site footer

Region positions

Region	Default contents
`top`	—
`left`	—
`right`	—
`bottom`	—

Minimal working example

// karaoke.config.ts
import { defineConfig } from '@karaoke-cms/astro';
import { loadEnv } from '@karaoke-cms/astro/env';
import { blog } from '@karaoke-cms/module-blog';
import { docs } from '@karaoke-cms/module-docs';
import { tags } from '@karaoke-cms/module-tags';
import { search } from '@karaoke-cms/module-search';
import { seo } from '@karaoke-cms/module-seo';
import { comments } from '@karaoke-cms/module-comments';
import { themeDefault } from '@karaoke-cms/theme-default';

const env = loadEnv(new URL('.', import.meta.url));

export default defineConfig({
  vault:       env.KARAOKE_VAULT,
  title:       'My Site',
  description: 'What this site is about.',
  theme:       themeDefault(),
  modules: [
    blog({ mount: '/blog', comments: true }),
    docs({ mount: '/docs' }),
    tags(),
    search(),
    seo(),
    comments({
      repo:       'owner/repo',
      repoId:     'R_...',
      category:   'General',
      categoryId: 'DIC_...',
    }),
  ],
});

Configuration Reference

defineConfig()

KaraokeConfig type

Top-level options

CollectionConfig type

CommentsConfig type

blog()

BlogConfig options

Routes injected

Menu entries registered

docs()

DocsConfig options (single-section form)

DocsSection fields (array form)

Routes injected (per instance, via codegen)

Menu entries registered

tags()

TagsConfig options

Routes injected

Menu entries registered

search()

Options

Routes injected

Menu entries registered

Notes

comments()

CommentsConfig options

Routes injected

Menu entries registered

seo()

SeoConfig options

Routes injected

Menu entries registered

Layout regions

RegionComponent values

Region positions

Minimal working example