npm package: @karaoke-cms/theme-default
Description: Default theme for karaoke-cms — two-column knowledge base with blog and docs
Latest version: 0.20.10

# @karaoke-cms/theme-default

Two-column knowledge base theme for karaoke-cms — blog, docs, and tags with a clean system-UI design and automatic dark mode.

## Installation

```bash
npm install @karaoke-cms/theme-default @karaoke-cms/module-blog @karaoke-cms/module-docs
```

## Usage

```ts
// 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 { themeDefault } from '@karaoke-cms/theme-default';

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

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

## Configuration

`themeDefault()` takes no arguments. Pass modules via `modules: []` in `defineConfig()` — the core integration passes them to the theme at build time.

## Routes

| Route | Description |
|-------|-------------|
| `/` | Home — recent blog posts + recent docs |
| `/blog`, `/blog/[slug]`, `/blog/page/[page]` | Blog section (from `module-blog`) |
| `/docs`, `/docs/list`, `/docs/[slug]` | Docs section (from `module-docs`) |
| `/tags` | All tags with post counts |
| `/tags/[tag]` | Posts filtered by tag |
| `/404` | Not found page |

Routes for modules listed in `modules[]` are injected by the module package. Other routes (tags, 404, home) are injected by the theme as fallbacks.

## Design system

All tokens are CSS variables on `:root`:

- **Typography**: `--font-body`, `--font-mono`, `--font-size-base`, `--font-size-sm/lg/xl`
- **Color**: `--color-bg`, `--color-text`, `--color-muted`, `--color-border`, `--color-link`
- **Spacing**: `--spacing-xs/sm/md/lg/xl`
- **Sizing**: `--width-content` (680px), `--width-site` (800px)

Dark mode is automatic via `@media (prefers-color-scheme: dark)` — no JavaScript toggle.

## Layout regions

Configure sidebar content in `karaoke.config.ts`:

```ts
layout: {
  regions: {
    right: { components: ['recent-posts'] },
  },
}
```

Available: `'header'`, `'main-menu'`, `'search'`, `'recent-posts'`, `'footer'`.

## What's new in 0.19.0

- **CSS cascade refactored** — styles now import from `@karaoke-cms/theme-base` (tokens + base structural CSS) instead of shipping everything inline. Override tokens in `:root` for easy customization.
- **SiteHeader and SiteFooter extracted to components** — `SiteHeader.astro` and `SiteFooter.astro` are now standalone components exported from the package, making them easier to override or compose.
- **Module CSS split** — each module now ships its own CSS file (e.g. `blog-styles.css`, `docs-styles.css`) instead of bundling all module styles in the theme.

## What's new in 0.18.2

- **`layout.config.ts` for variant layout overrides** -- the theme now ships a `layout.config.ts` file declaring per-variant layout customizations using `defineLayoutConfig()` from `@karaoke-cms/contracts`. For example, `karaoke.blog.post` is configured with body content in `main` and a recent-posts sidebar in `right`. Theme authors can add or modify variant keys in this file to change the default layout for any page type.
- **`layoutOverrides` on `ThemeInstance`** -- the theme factory now returns `layoutOverrides` on its `ThemeInstance`, which the core integration merges between module defaults and user overrides. This gives themes a dedicated layer in the three-tier layout resolution (module -> theme -> user).

## What's new in 0.18.1

- **New landing page** — the default `/` home page now shows a "Your site is live" hero and your three most recent blog posts, giving a working first impression out of the box. Override it by adding `src/pages/index.astro` to your project.

## What's new in 0.18.0

- **Docs section switcher** -- when multiple docs sections are configured, a styled navigation bar appears with a heading, pill-style links, and an active state using `--color-accent`. New CSS classes: `.docs-section-switcher`, `.docs-section-switcher-title`, `.docs-section-switcher-list`, `.docs-section-link`.

## What's new in 0.17.0

- **`themeDefault()` takes no arguments** — the `implements: []` option is removed. Pass modules via `modules: []` in `defineConfig()` instead.
- **Submenu rendering** — the main nav renders hover/click submenus for entries with nested children (from `parent:` in `menus.yaml` or `parent:` on `DocsSection` array items). A toggle button is included for keyboard and touch accessibility.

## What's new in 0.13.1

No user-facing changes in this release.

## What's new in 0.10.2

- **Section-aware tags and RSS** — `/tags`, `/tags/[tag]`, and `/rss.xml` now aggregate entries across all active docs sections, not just the default `/docs` section.
- No other user-facing visual changes in this release.

## What's new in 0.9.5

- **`themeDefault()` function API** replaces the old string `theme: '@karaoke-cms/theme-default'`
- **`implements` option** — pass `blog()` and/or `docs()` module instances to wire up content sections; routes come from the module packages
- No user-facing visual changes in this release