Themes

A theme controls the visual layout, typography, colors, and component structure of your site. Modules declare the CSS class names they use; the theme provides the styles for those classes. Switching themes changes the look of the entire site without touching your content.

Both built-in themes adapt automatically to which modules are active — if you add or remove blog(), docs(), or tags() from your config, the theme adjusts its navigation and layout without any extra configuration.

Available themes

themeDefault

A two-column layout with a sidebar, header navigation, and full-width content area. Works well with all modules and is the best choice for documentation-heavy sites or sites that combine blog posts with structured docs sections.

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

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

themeBlog

An editorial layout with a featured hero post, card grid, and support for cover images. Designed for blog-first sites where the homepage showcases recent posts. Works best when blog() is your primary module; documentation needs are minimal.

import { defineConfig } from '@karaoke-cms/astro';
import { themeBlog } from '@karaoke-cms/theme-blog';
import { blog } from '@karaoke-cms/module-blog';
import { tags } from '@karaoke-cms/module-tags';

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

Switching themes

Change the theme: field in karaoke.config.ts and update the import:

// Before
import { themeDefault } from '@karaoke-cms/theme-default';
theme: themeDefault(),

// After
import { themeBlog } from '@karaoke-cms/theme-blog';
theme: themeBlog(),

No other changes are needed. Run pnpm dev to preview the new theme.

Custom themes

If the built-in themes don’t fit your design, you can build a custom theme. See Custom themes for the full guide.