@karaoke-cms/theme-default 0.9.3 → 0.9.5

package/README.md

@@ -1,65 +1,85 @@
 # @karaoke-cms/theme-default
 
-Two-column knowledge base theme for karaoke-cms. Includes blog, docs, and tags sections with a clean system-UI design.
+Two-column knowledge base theme for karaoke-cms — blog, docs, and tags with a clean system-UI design and automatic dark mode.
 
-## Where it belongs
+## Installation
 
-`packages/theme-default/` in the monorepo. Activated via `karaoke.config.ts`:
+```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';
-const { KARAOKE_VAULT } = loadEnv(new URL('.', import.meta.url));
-
-export default {
-  vault: KARAOKE_VAULT,
-  theme: '@karaoke-cms/theme-default',
-};
+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({
+    implements: [
+      blog({ mount: '/blog' }),
+      docs({ mount: '/docs' }),
+    ],
+  }),
+});
 ```
 
-`@karaoke-cms/astro` resolves the theme string to this package and loads it as a nested Astro integration at build time.
+## Configuration
+
+Pass modules to `implements` to tell the theme which content sections to wire up. Modules listed here get their routes injected from their own npm packages.
 
-## What it does
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `implements` | `ModuleInstance[]` | `[]` | Content modules this theme integrates |
 
-Injects all site routes and sets the `@theme` Vite alias so that `Base.astro` can resolve `@theme/styles.css`:
+## Routes
 
-| Route | Page |
-|-------|------|
+| Route | Description |
+|-------|-------------|
 | `/` | Home — recent blog posts + recent docs |
-| `/blog` | Blog index — all published posts, sorted by date |
-| `/blog/[slug]` | Blog post — full content with related posts |
-| `/docs` | Docs index — all published docs, sorted alphabetically |
-| `/docs/[slug]` | Doc page — full content |
-| `/tags` | Tags index — all tags with post counts |
-| `/tags/[tag]` | Tag page — posts filtered by tag |
+| `/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 |
 
-### Design system
+Routes for modules listed in `implements` are injected by the module package. Other routes are injected by the theme as fallbacks.
 
-`src/styles.css` defines all tokens as CSS variables on `:root`:
+## 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`, `--color-link-hover`, `--color-link-visited`
+- **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), `--radius-sm`
+- **Sizing**: `--width-content` (680px), `--width-site` (800px)
 
 Dark mode is automatic via `@media (prefers-color-scheme: dark)` — no JavaScript toggle.
 
-## How to use
+## Layout regions
 
-Install alongside `@karaoke-cms/astro`:
+Configure sidebar content in `karaoke.config.ts`:
 
-```bash
-npm install @karaoke-cms/astro @karaoke-cms/theme-default
+```ts
+layout: {
+  regions: {
+    right: { components: ['recent-posts'] },
+  },
+}
 ```
 
-Set `theme: '@karaoke-cms/theme-default'` (or omit — it's the default) in `karaoke.config.ts`.
-
-Your vault needs `blog/` and/or `docs/` directories with Markdown files. Only files with `publish: true` in frontmatter appear on the site.
+Available: `'header'`, `'main-menu'`, `'search'`, `'recent-posts'`, `'footer'`.
 
-## How it changes the behavior of the system
+## What's new in 0.9.5
 
-- Provides the only routes that make up the site's public pages. Without a theme, nothing is served at `/`.
-- The `@theme` alias means `Base.astro` and all pages resolve styles and components from this package at build time. Switching themes is a one-line change in `karaoke.config.ts`.
-- Does not include `/docs` routes — that differentiates it from `theme-blog`. Suitable for mixed blog + documentation sites.
-- The layout is driven by `Base.astro`'s region system — sidebar content (recent posts, search) is controlled by the `layout.regions` config in `karaoke.config.ts`, not hardcoded in the theme.
+- **`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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@karaoke-cms/theme-default",
   "type": "module",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "description": "Default theme for karaoke-cms — two-column knowledge base with blog and docs",
   "main": "./src/index.ts",
   "exports": {
@@ -17,11 +17,11 @@
     "karaoke-cms"
   ],
   "dependencies": {
-    "@karaoke-cms/module-blog": "workspace:*"
+    "@karaoke-cms/module-blog": "^0.9.5"
   },
   "peerDependencies": {
     "astro": ">=6.0.0",
-    "@karaoke-cms/astro": "^0.9.2"
+    "@karaoke-cms/astro": "^0.9.5"
   },
   "devDependencies": {
     "@karaoke-cms/astro": "workspace:*",

package/src/index.ts

@@ -1,4 +1,5 @@
 import type { AstroIntegration } from 'astro';
+import type { ModuleInstance } from '@karaoke-cms/astro';
 import { fileURLToPath } from 'url';
 import { existsSync } from 'fs';
 
@@ -7,27 +8,30 @@ const __dirname = fileURLToPath(new URL('.', import.meta.url));
 // Constructs the Astro integration for theme-default.
 // Exported separately so it can be called by both the new factory (themeDefault)
 // and the legacy default export without triggering a @karaoke-cms/astro import.
-function buildIntegration(): AstroIntegration {
+//
+// When `implementedModuleIds` is provided, routes for those modules are skipped —
+// the core integration injects them from the module package instead.
+function buildIntegration(implementedModuleIds: string[] = []): AstroIntegration {
   return {
     name: '@karaoke-cms/theme-default',
     hooks: {
       'astro:config:setup': ({ injectRoute, updateConfig, config: astroConfig }) => {
-        // Blog routes are owned by @karaoke-cms/module-blog.
-        // theme-default injects them here so that the old string-based theme
-        // config (theme: '@karaoke-cms/theme-default') continues to work.
-        // When the new modules[] array config is fully adopted, theme-default
-        // will stop injecting these and let the core integration do it.
-        injectRoute({ pattern: '/blog',         entrypoint: '@karaoke-cms/module-blog/pages/list' });
-        injectRoute({ pattern: '/blog/[slug]',  entrypoint: '@karaoke-cms/module-blog/pages/post' });
+        // Blog post route: fall back to module-blog post page when blog is not in implements[].
+        if (!implementedModuleIds.includes('blog')) {
+          injectRoute({ pattern: '/blog/[slug]',  entrypoint: '@karaoke-cms/module-blog/pages/post' });
+        }
+
+        // Docs routes: fall back to built-in pages when docs is not in implements[].
+        if (!implementedModuleIds.includes('docs')) {
+          injectRoute({ pattern: '/docs',         entrypoint: `${__dirname}pages/docs/index.astro` });
+          injectRoute({ pattern: '/docs/[slug]',  entrypoint: `${__dirname}pages/docs/[slug].astro` });
+        }
 
-        // Docs, tags, and homepage remain owned by theme-default.
         // Skip injecting '/' if the user already has src/pages/index.astro.
         const userIndex = fileURLToPath(new URL('src/pages/index.astro', astroConfig.root));
         if (!existsSync(userIndex)) {
           injectRoute({ pattern: '/', entrypoint: `${__dirname}pages/index.astro` });
         }
-        injectRoute({ pattern: '/docs',         entrypoint: `${__dirname}pages/docs/index.astro` });
-        injectRoute({ pattern: '/docs/[slug]',  entrypoint: `${__dirname}pages/docs/[slug].astro` });
         injectRoute({ pattern: '/tags',         entrypoint: `${__dirname}pages/tags/index.astro` });
         injectRoute({ pattern: '/tags/[tag]',   entrypoint: `${__dirname}pages/tags/[tag].astro` });
         injectRoute({ pattern: '/404',          entrypoint: `${__dirname}pages/404.astro` });
@@ -47,10 +51,6 @@ function buildIntegration(): AstroIntegration {
 /**
  * New API: returns a ThemeInstance for use with defineConfig().
  *
- * Note: ThemeInstance is constructed manually here (without importing defineTheme
- * from @karaoke-cms/astro) so that this file remains loadable via Node's native
- * ESM when used through the legacy string-based theme config path.
- *
  * @example
  * // karaoke.config.ts
  * import { themeDefault } from '@karaoke-cms/theme-default';
@@ -58,12 +58,15 @@ function buildIntegration(): AstroIntegration {
  *   theme: themeDefault({ implements: [blog({ mount: '/blog' })] }),
  * });
  */
-export function themeDefault(config: { implements?: Array<{ id: string }> } = {}) {
+export function themeDefault(config: { implements?: ModuleInstance[] } = {}) {
+  const implementedModules = config.implements ?? [];
+  const implementedModuleIds = implementedModules.map(m => m.id);
   return {
     _type: 'theme-instance' as const,
     id: 'theme-default',
-    implementedModuleIds: (config.implements ?? []).map(m => m.id),
-    toAstroIntegration: () => buildIntegration(),
+    implementedModuleIds,
+    implementedModules,
+    toAstroIntegration: () => buildIntegration(implementedModuleIds),
   };
 }
 
@@ -72,7 +75,9 @@ export function themeDefault(config: { implements?: Array<{ id: string }> } = {}
  *   theme: '@karaoke-cms/theme-default'
  * The core integration calls themeModule.default(config) when loading
  * themes by package name string.
+ *
+ * Injects blog routes directly (legacy path — blog module not in modules[]).
  */
 export default function themeDefaultLegacy(_config: unknown): AstroIntegration {
-  return buildIntegration();
+  return buildIntegration([]);
 }

package/src/styles.css

@@ -87,6 +87,10 @@ header {
   margin-bottom: var(--spacing-xl);
 }
 
+header.landing-header {
+  margin-bottom: 0;
+}
+
 .header-inner {
   max-width: var(--width-landing);
   margin: 0 auto;
@@ -107,6 +111,10 @@ header {
   letter-spacing: -0.01em;
 }
 
+.site-name:visited {
+  color: var(--color-on-dark);
+}
+
 .site-name:hover {
   color: #fff;
 }
@@ -134,6 +142,10 @@ header nav ul a {
   transition: color 0.15s;
 }
 
+header nav ul a:visited {
+  color: #94a3b8;
+}
+
 header nav ul a:hover,
 header nav ul a[aria-current="page"] {
   color: var(--color-on-dark);
@@ -271,6 +283,10 @@ footer a {
   text-decoration: none;
 }
 
+footer a:visited {
+  color: var(--color-on-dark-2);
+}
+
 footer a:hover {
   color: var(--color-on-dark);
 }
@@ -284,6 +300,10 @@ footer a:hover {
   padding-bottom: var(--spacing-xs);
 }
 
+.footer-col nav.karaoke-menu > ul > li > a:visited {
+  color: var(--color-on-dark);
+}
+
 .footer-col nav.karaoke-menu > ul > li > ul a {
   font-size: var(--font-size-sm);
   color: #94a3b8;
@@ -291,6 +311,10 @@ footer a:hover {
   padding: 2px 0;
 }
 
+.footer-col nav.karaoke-menu > ul > li > ul a:visited {
+  color: #94a3b8;
+}
+
 .footer-col nav.karaoke-menu > ul > li > ul a:hover {
   color: var(--color-on-dark);
 }
@@ -616,12 +640,12 @@ nav.karaoke-menu[data-orientation="vertical"] li ul {
 
 /* ── Header CTA button ──────────────────────────────────────────────── */
 
-.btn-cta {
+a.btn-cta {
   font-size: var(--font-size-sm);
   font-weight: 600;
   color: #fff;
   background: var(--color-accent);
-  padding: 5px 14px;
+  padding: 6px 20px;
   border-radius: 999px;
   text-decoration: none;
   transition: opacity 0.15s;
@@ -629,8 +653,9 @@ nav.karaoke-menu[data-orientation="vertical"] li ul {
   white-space: nowrap;
 }
 
-.btn-cta:hover,
-.btn-cta:visited {
+a.btn-cta:link,
+a.btn-cta:visited,
+a.btn-cta:hover {
   opacity: 0.85;
   color: #fff;
   text-decoration: none;