@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

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

Usage

// 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:

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