@karaoke-cms/astro 0.6.1 → 0.6.3

package/client.d.ts

@@ -6,7 +6,7 @@
  */
 
 declare module 'virtual:karaoke-cms/config' {
-  import type { ResolvedModules, ResolvedLayout } from '@karaoke-cms/astro';
+  import type { ResolvedModules, ResolvedLayout, ResolvedCollections } from '@karaoke-cms/astro';
 
   /** Site title from karaoke.config.ts */
   export const siteTitle: string;
@@ -16,4 +16,6 @@ declare module 'virtual:karaoke-cms/config' {
   export const resolvedModules: ResolvedModules;
   /** Resolved layout config (defaults filled in) */
   export const resolvedLayout: ResolvedLayout;
+  /** Resolved collections with enabled/disabled status for current build mode */
+  export const resolvedCollections: ResolvedCollections;
 }

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@karaoke-cms/astro",
   "type": "module",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Astro integration for karaoke-cms — ships all routes, themes, and modules",
   "main": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
     "./client": "./client.d.ts",
     "./collections": "./src/collections.ts",
+    "./env": "./src/utils/load-env.ts",
     "./pages/index.astro": "./src/pages/index.astro",
     "./pages/blog/index.astro": "./src/pages/blog/index.astro",
     "./pages/blog/[slug].astro": "./src/pages/blog/[slug].astro",
@@ -16,7 +17,9 @@
     "./pages/tags/index.astro": "./src/pages/tags/index.astro",
     "./pages/tags/[tag].astro": "./src/pages/tags/[tag].astro",
     "./pages/404.astro": "./src/pages/404.astro",
-    "./pages/rss.xml.ts": "./src/pages/rss.xml.ts"
+    "./pages/rss.xml.ts": "./src/pages/rss.xml.ts",
+    "./pages/karaoke-cms/index.astro": "./src/pages/karaoke-cms/index.astro",
+    "./pages/karaoke-cms/[...slug].astro": "./src/pages/karaoke-cms/[...slug].astro"
   },
   "files": [
     "src/",
@@ -34,13 +37,14 @@
   "dependencies": {
     "@astrojs/rss": "^4.0.17",
     "@astrojs/sitemap": "^3.7.1",
-    "remark-wiki-link": "^2.0.1"
+    "remark-wiki-link": "^2.0.1",
+    "yaml": "^2.7.0"
   },
   "devDependencies": {
     "vitest": "^4.1.1",
     "astro": "^6.0.8"
   },
   "scripts": {
-    "test": "vitest run test/validate-config.test.js test/resolve-modules.test.js test/resolve-layout.test.js"
+    "test": "vitest run test/validate-config.test.js test/resolve-modules.test.js test/resolve-layout.test.js test/resolve-collections.test.js test/load-env.test.js"
   }
 }

package/src/collections.ts

@@ -1,7 +1,9 @@
 import { defineCollection, z } from 'astro:content';
 import { glob } from 'astro/loaders';
 import { fileURLToPath } from 'url';
-import { join } from 'path';
+import { join, resolve, isAbsolute } from 'path';
+import { resolveCollections } from './utils/resolve-collections.js';
+import type { CollectionConfig } from './types.js';
 
 const baseSchema = z.object({
   title: z.string(),
@@ -15,28 +17,83 @@ const baseSchema = z.object({
   related: z.array(z.string()).optional(),
 });
 
+// Relaxed schema for handbook / custom collections — title is optional
+const relaxedSchema = z.object({
+  title: z.string().optional().default('Untitled'),
+  publish: z.boolean().optional().default(false),
+  date: z.coerce.date().optional(),
+  author: z.union([z.string(), z.array(z.string())]).optional(),
+  tags: z.array(z.string()).optional(),
+  description: z.string().optional(),
+  reading_time: z.number().optional(),
+  related: z.array(z.string()).optional(),
+});
+
 /**
  * Create Astro content collections for karaoke-cms.
  *
- * @param root - URL pointing to the project root (where content/ lives).
- *   Typically: `new URL('../..', import.meta.url)` from src/content.config.ts
+ * Reads collections.yaml from the vault to determine which collections are
+ * active for the current build mode. The `karaoke-cms` collection (handbook)
+ * is dev-only and never enters the production build graph.
+ *
+ * @param root - URL pointing to the Astro project root (where astro.config.mjs lives).
+ *   Typically: `new URL('..', import.meta.url)` from src/content.config.ts
+ * @param vault - Path to the Obsidian vault root (where content/ lives).
+ *   Absolute, or relative to `root`. Defaults to `root` when omitted (vault = project).
+ *   Typically sourced from `loadEnv(new URL('..', import.meta.url)).KARAOKE_VAULT`.
+ * @param configCollections - Optional per-collection overrides from karaoke.config.ts.
  *
  * @example
  * // src/content.config.ts
  * import { makeCollections } from '@karaoke-cms/astro/collections';
- * export const collections = makeCollections(new URL('../..', import.meta.url));
+ * import { loadEnv } from '@karaoke-cms/astro/env';
+ * const env = loadEnv(new URL('..', import.meta.url));
+ * export const collections = makeCollections(new URL('..', import.meta.url), env.KARAOKE_VAULT);
  */
-export function makeCollections(root: URL) {
+export function makeCollections(
+  root: URL,
+  vault?: string,
+  configCollections?: Record<string, CollectionConfig>,
+) {
   const rootDir = fileURLToPath(root);
-  return {
-    // base paths are absolute, resolving content/ relative to the project root
-    blog: defineCollection({
-      loader: glob({ pattern: '**/*.md', base: join(rootDir, 'content/blog') }),
+  const vaultDir = vault
+    ? (isAbsolute(vault) ? vault : resolve(rootDir, vault))
+    : rootDir;
+  const isProd = import.meta.env.PROD;
+  const resolved = resolveCollections(vaultDir, isProd, configCollections);
+
+  const collections: Record<string, ReturnType<typeof defineCollection>> = {};
+
+  if (resolved.blog?.enabled) {
+    collections.blog = defineCollection({
+      loader: glob({ pattern: '**/*.md', base: join(vaultDir, 'blog') }),
       schema: baseSchema.extend({ comments: z.boolean().optional().default(true) }),
-    }),
-    docs: defineCollection({
-      loader: glob({ pattern: '**/*.md', base: join(rootDir, 'content/docs') }),
+    });
+  }
+
+  if (resolved.docs?.enabled) {
+    collections.docs = defineCollection({
+      loader: glob({ pattern: '**/*.md', base: join(vaultDir, 'docs') }),
       schema: baseSchema.extend({ comments: z.boolean().optional().default(false) }),
-    }),
-  };
+    });
+  }
+
+  if (resolved['karaoke-cms']?.enabled) {
+    collections['karaoke-cms'] = defineCollection({
+      loader: glob({ pattern: '**/*.md', base: join(vaultDir, 'karaoke-cms') }),
+      schema: relaxedSchema,
+    });
+  }
+
+  // Custom collections defined in yaml or configCollections
+  for (const [name, col] of Object.entries(resolved)) {
+    if (!collections[name] && col.enabled) {
+      collections[name] = defineCollection({
+        loader: glob({ pattern: '**/*.md', base: join(vaultDir, name) }),
+        schema: relaxedSchema,
+      });
+    }
+  }
+
+  return collections;
 }

package/src/components/regions/RecentPosts.astro

@@ -1,9 +1,17 @@
 ---
 import { getCollection } from 'astro:content';
 
-const posts = (await getCollection('blog', ({ data }) => data.publish === true))
+const LIMIT = 5;
+
+// Detect which collection we're in and exclude the current page
+const pathname = Astro.url.pathname.replace(/\/$/, '');
+const collection = pathname.startsWith('/docs/') ? 'docs' : 'blog';
+const currentSlug = pathname.split('/').at(-1) ?? '';
+
+const posts = (await getCollection(collection, ({ data }) => data.publish === true))
   .sort((a, b) => (b.data.date?.valueOf() ?? 0) - (a.data.date?.valueOf() ?? 0))
-  .slice(0, 5);
+  .filter(post => post.id !== currentSlug)
+  .slice(0, LIMIT);
 ---
 
 {posts.length > 0 && (
@@ -12,7 +20,7 @@ const posts = (await getCollection('blog', ({ data }) => data.publish === true))
     <ul class="sidebar-list">
       {posts.map(post => (
         <li>
-          <a href={`/blog/${post.id}`}>{post.data.title}</a>
+          <a href={`/${collection}/${post.id}`}>{post.data.title}</a>
           {post.data.date && (
             <span class="post-date">{post.data.date.toISOString().slice(0, 10)}</span>
           )}

package/src/index.ts

@@ -1,12 +1,13 @@
 import type { AstroIntegration } from 'astro';
 import { fileURLToPath } from 'url';
-import { join } from 'path';
+import { join, resolve, isAbsolute } from 'path';
 import { wikiLinkPlugin } from 'remark-wiki-link';
 import sitemap from '@astrojs/sitemap';
 import { getTheme, validateModules } from './validate-config.js';
 import { resolveModules } from './utils/resolve-modules.js';
 import { resolveLayout } from './utils/resolve-layout.js';
-import type { KaraokeConfig, ResolvedModules, ResolvedLayout } from './types.js';
+import { resolveCollections } from './utils/resolve-collections.js';
+import type { KaraokeConfig, ResolvedModules, ResolvedLayout, ResolvedCollections } from './types.js';
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 
@@ -17,6 +18,8 @@ const __dirname = fileURLToPath(new URL('.', import.meta.url));
  * /tags, /tags/[tag], /rss.xml, /404), sets up the @theme CSS alias,
  * enables wikilinks, and provides a virtual module with your resolved config.
  *
+ * The /karaoke-cms and /karaoke-cms/[...slug] routes are injected in dev only.
+ *
  * @example
  * // astro.config.mjs
  * import { defineConfig } from 'astro/config';
@@ -42,7 +45,14 @@ export default function karaoke(config: KaraokeConfig = {}): AstroIntegration {
   return {
     name: '@karaoke-cms/astro',
     hooks: {
-      'astro:config:setup'({ injectRoute, updateConfig }) {
+      'astro:config:setup'({ injectRoute, updateConfig, command, config: astroConfig }) {
+        const rootDir = fileURLToPath(astroConfig.root);
+        const vaultDir = config.vault
+          ? (isAbsolute(config.vault) ? config.vault : resolve(rootDir, config.vault))
+          : rootDir;
+        const isProd = command === 'build';
+        const resolvedCollections = resolveCollections(vaultDir, isProd, config.collections);
+
         // ── Inject all framework routes ──────────────────────────────────
         injectRoute({ pattern: '/', entrypoint: '@karaoke-cms/astro/pages/index.astro' });
         injectRoute({ pattern: '/blog', entrypoint: '@karaoke-cms/astro/pages/blog/index.astro' });
@@ -54,6 +64,12 @@ export default function karaoke(config: KaraokeConfig = {}): AstroIntegration {
         injectRoute({ pattern: '/404', entrypoint: '@karaoke-cms/astro/pages/404.astro' });
         injectRoute({ pattern: '/rss.xml', entrypoint: '@karaoke-cms/astro/pages/rss.xml.ts' });
 
+        // ── Handbook routes — dev only ───────────────────────────────────
+        if (resolvedCollections['karaoke-cms']?.enabled) {
+          injectRoute({ pattern: '/karaoke-cms', entrypoint: '@karaoke-cms/astro/pages/karaoke-cms/index.astro' });
+          injectRoute({ pattern: '/karaoke-cms/[...slug]', entrypoint: '@karaoke-cms/astro/pages/karaoke-cms/[...slug].astro' });
+        }
+
         updateConfig({
           integrations: [sitemap()],
           vite: {
@@ -63,7 +79,7 @@ export default function karaoke(config: KaraokeConfig = {}): AstroIntegration {
                 '@theme': join(themesDir, theme),
               },
             },
-            plugins: [virtualConfigPlugin(config, resolved, layout)],
+            plugins: [virtualConfigPlugin(config, resolved, layout, resolvedCollections)],
           },
           markdown: {
             remarkPlugins: [
@@ -87,7 +103,12 @@ export default function karaoke(config: KaraokeConfig = {}): AstroIntegration {
  * Vite plugin providing `virtual:karaoke-cms/config`.
  * Base.astro and ModuleLoader.astro import from it at build time.
  */
-function virtualConfigPlugin(config: KaraokeConfig, resolved: ResolvedModules, layout: ResolvedLayout) {
+function virtualConfigPlugin(
+  config: KaraokeConfig,
+  resolved: ResolvedModules,
+  layout: ResolvedLayout,
+  resolvedCollections: ResolvedCollections,
+) {
   const VIRTUAL_ID = 'virtual:karaoke-cms/config';
   const RESOLVED_ID = '\0' + VIRTUAL_ID;
 
@@ -103,10 +124,11 @@ export const siteTitle = ${JSON.stringify(config.title ?? 'Karaoke')};
 export const siteDescription = ${JSON.stringify(config.description ?? '')};
 export const resolvedModules = ${JSON.stringify(resolved)};
 export const resolvedLayout = ${JSON.stringify(layout)};
+export const resolvedCollections = ${JSON.stringify(resolvedCollections)};
 `;
       }
     },
   };
 }
 
-export type { KaraokeConfig, ResolvedModules, ResolvedLayout, RegionComponent } from './types.js';
+export type { KaraokeConfig, ResolvedModules, ResolvedLayout, ResolvedCollections, RegionComponent } from './types.js';

package/src/pages/blog/index.astro

@@ -25,7 +25,7 @@ const posts = (await getCollection('blog', ({ data }) => data.publish === true))
   ) : (
     <div class="empty-state">
       <p>No posts published yet.</p>
-      <p>Create a Markdown file in <code>content/blog/</code> and set <code>publish: true</code> in the frontmatter to make it appear here.</p>
+      <p>Create a Markdown file in your vault's <code>blog/</code> folder and set <code>publish: true</code> in the frontmatter to make it appear here.</p>
     </div>
   )}
 </Base>

package/src/pages/docs/index.astro

@@ -25,7 +25,7 @@ const docs = (await getCollection('docs', ({ data }) => data.publish === true))
   ) : (
     <div class="empty-state">
       <p>No docs published yet.</p>
-      <p>Create a Markdown file in <code>content/docs/</code> and set <code>publish: true</code> in the frontmatter to make it appear here.</p>
+      <p>Create a Markdown file in your vault's <code>docs/</code> folder and set <code>publish: true</code> in the frontmatter to make it appear here.</p>
     </div>
   )}
 </Base>

package/src/pages/karaoke-cms/[...slug].astro

@@ -0,0 +1,44 @@
+---
+import { getCollection, render } from 'astro:content';
+import Base from '../../layouts/Base.astro';
+import { SITE_TITLE } from '../../consts';
+
+// Handbook is dev-only — this route is never injected in production.
+export async function getStaticPaths() {
+  const entries = await getCollection('karaoke-cms');
+  return entries.map(entry => ({
+    params: { slug: entry.id },
+    props: { entry },
+  }));
+}
+
+const { entry } = Astro.props;
+const { Content } = await render(entry);
+---
+
+<Base title={`${entry.data.title} — ${SITE_TITLE}`} description={entry.data.description}>
+  <article>
+    <div class="post-header">
+      <span class="handbook-badge">Handbook — dev only</span>
+      <h1>{entry.data.title}</h1>
+    </div>
+    <div class="prose">
+      <Content />
+    </div>
+    <div class="post-footer">
+      <a href="/karaoke-cms">← Handbook</a>
+    </div>
+  </article>
+</Base>
+
+<style>
+  .handbook-badge {
+    display: inline-block;
+    font-size: 0.75rem;
+    background: var(--color-accent, #f59e0b);
+    color: #000;
+    padding: 0.1rem 0.5rem;
+    border-radius: 999px;
+    margin-bottom: 0.5rem;
+  }
+</style>

package/src/pages/karaoke-cms/index.astro

@@ -0,0 +1,43 @@
+---
+import { getCollection } from 'astro:content';
+import Base from '../../layouts/Base.astro';
+import { SITE_TITLE } from '../../consts';
+
+// Handbook is dev-only — this route is never injected in production.
+// Show all entries (no publish filter — handbook pages are always visible in dev).
+const entries = (await getCollection('karaoke-cms'))
+  .sort((a, b) => (a.data.title ?? '').localeCompare(b.data.title ?? ''));
+---
+
+<Base title={`Handbook — ${SITE_TITLE}`}>
+  <div class="listing-header">
+    <h1>Handbook</h1>
+    <p class="handbook-badge">dev only</p>
+  </div>
+  {entries.length > 0 ? (
+    <ul class="post-list">
+      {entries.map(entry => (
+        <li>
+          <a href={`/karaoke-cms/${entry.id}`}>{entry.data.title}</a>
+        </li>
+      ))}
+    </ul>
+  ) : (
+    <div class="empty-state">
+      <p>No handbook pages found.</p>
+      <p>Add Markdown files to <code>content/karaoke-cms/</code> in your vault.</p>
+    </div>
+  )}
+</Base>
+
+<style>
+  .handbook-badge {
+    display: inline-block;
+    font-size: 0.75rem;
+    background: var(--color-accent, #f59e0b);
+    color: #000;
+    padding: 0.1rem 0.5rem;
+    border-radius: 999px;
+    margin-top: 0.25rem;
+  }
+</style>

package/src/types.ts

@@ -1,6 +1,30 @@
 export type RegionComponent = 'header' | 'main-menu' | 'search' | 'recent-posts' | 'footer';
 
+export type CollectionMode = 'dev' | 'prod';
+
+export interface CollectionConfig {
+  modes?: CollectionMode[];
+  label?: string;
+}
+
+export interface ResolvedCollection {
+  modes: CollectionMode[];
+  label: string;
+  enabled: boolean;
+}
+
+export type ResolvedCollections = Record<string, ResolvedCollection>;
+
 export interface KaraokeConfig {
+  /**
+   * Path to the Obsidian vault root (where content/ lives).
+   * Absolute, or relative to the Astro project root.
+   * Defaults to the project root (vault and project are the same directory).
+   * Typically set via KARAOKE_VAULT in .env (gitignored) with .env.default as fallback.
+   */
+  vault?: string;
+  /** Per-collection mode overrides. Merges with collections.yaml; this field takes precedence. */
+  collections?: Record<string, CollectionConfig>;
   /** Site title — displayed in the browser tab and nav bar. Defaults to 'Karaoke'. */
   title?: string;
   /** Site description — used in RSS feed and OG meta tags. */

package/src/utils/load-env.ts

@@ -0,0 +1,37 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+
+function parseEnvFile(filePath: string): Record<string, string> {
+  try {
+    const content = readFileSync(filePath, 'utf8');
+    const result: Record<string, string> = {};
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      const eq = trimmed.indexOf('=');
+      if (eq === -1) continue;
+      const key = trimmed.slice(0, eq).trim();
+      const val = trimmed.slice(eq + 1).trim().replace(/^["']|["']$/g, '');
+      if (key) result[key] = val;
+    }
+    return result;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Load env vars from .env.default (committed defaults) and .env (local overrides).
+ * .env takes precedence over .env.default.
+ * Missing files are silently skipped.
+ *
+ * @param dir - URL or path of the directory containing the .env files.
+ */
+export function loadEnv(dir: URL | string): Record<string, string> {
+  const dirPath = dir instanceof URL ? fileURLToPath(dir) : dir;
+  return {
+    ...parseEnvFile(join(dirPath, '.env.default')),
+    ...parseEnvFile(join(dirPath, '.env')),
+  };
+}

package/src/utils/resolve-collections.ts

@@ -0,0 +1,83 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { parse } from 'yaml';
+import type { CollectionConfig, CollectionMode, ResolvedCollections } from '../types.js';
+
+// Hardcoded defaults — used when collections.yaml is absent or unreadable.
+// karaoke-cms is dev-only so it never enters the production build graph.
+const DEFAULTS: Record<string, { modes: CollectionMode[]; label: string }> = {
+  blog: { modes: ['dev', 'prod'], label: 'Blog' },
+  docs: { modes: ['dev', 'prod'], label: 'Docs' },
+  'karaoke-cms': { modes: ['dev'], label: 'Handbook' },
+};
+
+interface YamlShape {
+  collections?: Record<string, { modes?: string[]; label?: string }>;
+}
+
+/**
+ * Resolve the active content collections for the current build mode.
+ *
+ * Data flow:
+ *   DEFAULTS
+ *     ← merged with collections.yaml  (YAML overrides defaults per-key)
+ *     ← merged with configCollections (karaoke.config.ts overrides per-key)
+ *     → filter by isProd
+ *     → ResolvedCollections
+ *
+ * @param rootDir  Absolute path to the vault root (where blog/, docs/, karaoke-cms/ live).
+ * @param isProd   True during `astro build`, false during `astro dev`.
+ * @param configCollections  Optional overrides from karaoke.config.ts `collections` field.
+ */
+export function resolveCollections(
+  rootDir: string,
+  isProd: boolean,
+  configCollections?: Record<string, CollectionConfig>,
+): ResolvedCollections {
+  // 1. Read and parse collections.yaml (graceful fallback to defaults if absent)
+  let yamlCollections: Record<string, { modes?: CollectionMode[]; label?: string }> = {};
+  try {
+    const yamlPath = join(rootDir, 'karaoke-cms/config/collections.yaml');
+    const raw = readFileSync(yamlPath, 'utf8');
+    const parsed = parse(raw) as YamlShape;
+    if (parsed?.collections && typeof parsed.collections === 'object') {
+      for (const [name, val] of Object.entries(parsed.collections)) {
+        yamlCollections[name] = {
+          modes: Array.isArray(val?.modes)
+            ? (val.modes.filter(m => m === 'dev' || m === 'prod') as CollectionMode[])
+            : undefined,
+          label: typeof val?.label === 'string' ? val.label : undefined,
+        };
+      }
+    }
+  } catch {
+    // File absent or unreadable — use hardcoded defaults
+  }
+
+  // 2. Merge: DEFAULTS ← yaml ← configCollections
+  const allNames = new Set([
+    ...Object.keys(DEFAULTS),
+    ...Object.keys(yamlCollections),
+    ...(configCollections ? Object.keys(configCollections) : []),
+  ]);
+
+  const result: ResolvedCollections = {};
+  for (const name of allNames) {
+    const base = DEFAULTS[name];
+    const yaml = yamlCollections[name];
+    const cfg = configCollections?.[name];
+
+    const modes: CollectionMode[] =
+      cfg?.modes ?? yaml?.modes ?? base?.modes ?? ['dev', 'prod'];
+    const label: string =
+      cfg?.label ?? yaml?.label ?? base?.label ?? name;
+
+    result[name] = {
+      modes,
+      label,
+      enabled: isProd ? modes.includes('prod') : modes.includes('dev'),
+    };
+  }
+
+  return result;
+}