@karaoke-cms/astro 0.6.1

package/client.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Type declarations for karaoke-cms virtual modules.
+ *
+ * Add to your project's src/env.d.ts:
+ *   /// <reference types="@karaoke-cms/astro/client" />
+ */
+
+declare module 'virtual:karaoke-cms/config' {
+  import type { ResolvedModules, ResolvedLayout } from '@karaoke-cms/astro';
+
+  /** Site title from karaoke.config.ts */
+  export const siteTitle: string;
+  /** Site description from karaoke.config.ts */
+  export const siteDescription: string;
+  /** Resolved modules config (defaults filled in) */
+  export const resolvedModules: ResolvedModules;
+  /** Resolved layout config (defaults filled in) */
+  export const resolvedLayout: ResolvedLayout;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@karaoke-cms/astro",
+  "type": "module",
+  "version": "0.6.1",
+  "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",
+    "./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",
+    "./pages/docs/index.astro": "./src/pages/docs/index.astro",
+    "./pages/docs/[slug].astro": "./src/pages/docs/[slug].astro",
+    "./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"
+  },
+  "files": [
+    "src/",
+    "client.d.ts"
+  ],
+  "keywords": [
+    "astro",
+    "cms",
+    "obsidian",
+    "astro-integration"
+  ],
+  "peerDependencies": {
+    "astro": ">=6.0.0"
+  },
+  "dependencies": {
+    "@astrojs/rss": "^4.0.17",
+    "@astrojs/sitemap": "^3.7.1",
+    "remark-wiki-link": "^2.0.1"
+  },
+  "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"
+  }
+}

package/src/collections.ts

@@ -0,0 +1,42 @@
+import { defineCollection, z } from 'astro:content';
+import { glob } from 'astro/loaders';
+import { fileURLToPath } from 'url';
+import { join } from 'path';
+
+const baseSchema = z.object({
+  title: z.string(),
+  publish: z.boolean().optional().default(false), // missing = false (private by default)
+  date: z.coerce.date().optional(),
+  author: z.union([z.string(), z.array(z.string())]).optional(),
+  // v0.2 AI-enriched fields — optional so notes validate before and after enrichment
+  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
+ *
+ * @example
+ * // src/content.config.ts
+ * import { makeCollections } from '@karaoke-cms/astro/collections';
+ * export const collections = makeCollections(new URL('../..', import.meta.url));
+ */
+export function makeCollections(root: URL) {
+  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') }),
+      schema: baseSchema.extend({ comments: z.boolean().optional().default(true) }),
+    }),
+    docs: defineCollection({
+      loader: glob({ pattern: '**/*.md', base: join(rootDir, 'content/docs') }),
+      schema: baseSchema.extend({ comments: z.boolean().optional().default(false) }),
+    }),
+  };
+}

package/src/components/ModuleLoader.astro

@@ -0,0 +1,24 @@
+---
+// ModuleLoader.astro — renders per-page modules (comments) for blog/docs slug pages.
+// Search lives in Base.astro nav (slot: 'nav'); comments are here (slot: 'post-footer').
+import Comments from '../modules/comments/Comments.astro';
+import { resolvedModules } from 'virtual:karaoke-cms/config';
+
+interface Props {
+  /** Per-page frontmatter override. When provided, takes precedence over the config-level enabled flag. */
+  comments?: boolean;
+}
+
+const { comments } = Astro.props;
+const modules = resolvedModules;
+const showComments = comments !== undefined ? comments : modules.comments.enabled;
+---
+
+{showComments && modules.comments.repo && (
+  <Comments
+    repo={modules.comments.repo}
+    repoId={modules.comments.repoId}
+    category={modules.comments.category}
+    categoryId={modules.comments.categoryId}
+  />
+)}

package/src/components/RegionRenderer.astro

@@ -0,0 +1,24 @@
+---
+// RegionRenderer.astro — renders a pre-resolved list of components for a layout region.
+// Component order is fixed by the template below; the components array controls
+// which ones are present (included vs excluded).
+import SiteHeader from './regions/SiteHeader.astro';
+import MainMenu from './regions/MainMenu.astro';
+import SiteFooter from './regions/SiteFooter.astro';
+import RecentPosts from './regions/RecentPosts.astro';
+import Search from '../modules/search/Search.astro';
+import type { RegionComponent } from '../types.js';
+
+interface Props {
+  components: RegionComponent[];
+  searchEnabled: boolean;
+}
+
+const { components, searchEnabled } = Astro.props;
+---
+
+{components.includes('header')       && <SiteHeader />}
+{components.includes('main-menu')    && <MainMenu />}
+{components.includes('search')       && searchEnabled && <Search />}
+{components.includes('recent-posts') && <RecentPosts />}
+{components.includes('footer')       && <SiteFooter />}

package/src/components/regions/MainMenu.astro

@@ -0,0 +1,22 @@
+---
+const pathname = Astro.url.pathname;
+---
+<nav>
+  <ul>
+    <li>
+      <a href="/blog" aria-current={pathname.startsWith('/blog') ? 'page' : undefined}>
+        Blog
+      </a>
+    </li>
+    <li>
+      <a href="/docs" aria-current={pathname.startsWith('/docs') ? 'page' : undefined}>
+        Docs
+      </a>
+    </li>
+    <li>
+      <a href="/tags" aria-current={pathname.startsWith('/tags') ? 'page' : undefined}>
+        Tags
+      </a>
+    </li>
+  </ul>
+</nav>

package/src/components/regions/RecentPosts.astro

@@ -0,0 +1,23 @@
+---
+import { getCollection } from 'astro:content';
+
+const posts = (await getCollection('blog', ({ data }) => data.publish === true))
+  .sort((a, b) => (b.data.date?.valueOf() ?? 0) - (a.data.date?.valueOf() ?? 0))
+  .slice(0, 5);
+---
+
+{posts.length > 0 && (
+  <div class="sidebar-section">
+    <h3 class="sidebar-heading">Recent</h3>
+    <ul class="sidebar-list">
+      {posts.map(post => (
+        <li>
+          <a href={`/blog/${post.id}`}>{post.data.title}</a>
+          {post.data.date && (
+            <span class="post-date">{post.data.date.toISOString().slice(0, 10)}</span>
+          )}
+        </li>
+      ))}
+    </ul>
+  </div>
+)}

package/src/components/regions/SiteFooter.astro

@@ -0,0 +1,7 @@
+---
+---
+<div>
+  <a href="/rss.xml">RSS</a> · Built with
+  <a href="https://obsidian.md" rel="noopener">Obsidian</a> +
+  <a href="https://astro.build" rel="noopener">Astro</a>
+</div>

package/src/components/regions/SiteHeader.astro

@@ -0,0 +1,4 @@
+---
+import { SITE_TITLE } from '../../consts';
+---
+<a href="/" class="site-name">{SITE_TITLE}</a>

package/src/consts.ts

@@ -0,0 +1,8 @@
+/**
+ * Site constants — values come from the user's karaoke.config.ts via virtual module.
+ * This file is a thin re-export layer so pages can keep their existing import paths.
+ */
+import { siteTitle, siteDescription } from 'virtual:karaoke-cms/config';
+
+export const SITE_TITLE = siteTitle;
+export const SITE_DESCRIPTION = siteDescription;

package/src/index.ts

@@ -0,0 +1,112 @@
+import type { AstroIntegration } from 'astro';
+import { fileURLToPath } from 'url';
+import { join } 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';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+/**
+ * karaoke() — the main Astro integration for karaoke-cms.
+ *
+ * Injects all routes (/, /blog, /blog/[slug], /docs, /docs/[slug],
+ * /tags, /tags/[tag], /rss.xml, /404), sets up the @theme CSS alias,
+ * enables wikilinks, and provides a virtual module with your resolved config.
+ *
+ * @example
+ * // astro.config.mjs
+ * import { defineConfig } from 'astro/config';
+ * import karaoke from '@karaoke-cms/astro';
+ * import karaokeConfig from './karaoke.config.ts';
+ *
+ * export default defineConfig({
+ *   site: 'https://your-site.pages.dev',
+ *   integrations: [karaoke(karaokeConfig)],
+ * });
+ *
+ * Module slots (contract for Base.astro — extensible in v0.7+):
+ *   'nav'         — rendered in the nav bar (e.g., Search)
+ *   'post-footer' — rendered after post content (e.g., Comments)
+ */
+export default function karaoke(config: KaraokeConfig = {}): AstroIntegration {
+  const themesDir = join(__dirname, 'themes');
+  const theme = getTheme(config, themesDir);
+  validateModules(config);
+  const resolved = resolveModules(config);
+  const layout = resolveLayout(config);
+
+  return {
+    name: '@karaoke-cms/astro',
+    hooks: {
+      'astro:config:setup'({ injectRoute, updateConfig }) {
+        // ── Inject all framework routes ──────────────────────────────────
+        injectRoute({ pattern: '/', entrypoint: '@karaoke-cms/astro/pages/index.astro' });
+        injectRoute({ pattern: '/blog', entrypoint: '@karaoke-cms/astro/pages/blog/index.astro' });
+        injectRoute({ pattern: '/blog/[slug]', entrypoint: '@karaoke-cms/astro/pages/blog/[slug].astro' });
+        injectRoute({ pattern: '/docs', entrypoint: '@karaoke-cms/astro/pages/docs/index.astro' });
+        injectRoute({ pattern: '/docs/[slug]', entrypoint: '@karaoke-cms/astro/pages/docs/[slug].astro' });
+        injectRoute({ pattern: '/tags', entrypoint: '@karaoke-cms/astro/pages/tags/index.astro' });
+        injectRoute({ pattern: '/tags/[tag]', entrypoint: '@karaoke-cms/astro/pages/tags/[tag].astro' });
+        injectRoute({ pattern: '/404', entrypoint: '@karaoke-cms/astro/pages/404.astro' });
+        injectRoute({ pattern: '/rss.xml', entrypoint: '@karaoke-cms/astro/pages/rss.xml.ts' });
+
+        updateConfig({
+          integrations: [sitemap()],
+          vite: {
+            resolve: {
+              alias: {
+                // @theme → packages/astro/src/themes/<active-theme>/
+                '@theme': join(themesDir, theme),
+              },
+            },
+            plugins: [virtualConfigPlugin(config, resolved, layout)],
+          },
+          markdown: {
+            remarkPlugins: [
+              [wikiLinkPlugin, {
+                // [[blog/hello-world]] → /blog/hello-world/
+                // [[docs/getting-started]] → /docs/getting-started/
+                // [[blog/hello-world|Hello World]] → link text "Hello World"
+                pageResolver: (name: string) => [name.toLowerCase().replace(/ /g, '-')],
+                hrefTemplate: (permalink: string) => `/${permalink}/`,
+                aliasDivider: '|',
+              }],
+            ],
+          },
+        });
+      },
+    },
+  };
+}
+
+/**
+ * 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) {
+  const VIRTUAL_ID = 'virtual:karaoke-cms/config';
+  const RESOLVED_ID = '\0' + VIRTUAL_ID;
+
+  return {
+    name: 'vite-plugin-karaoke-cms-config',
+    resolveId(id: string) {
+      if (id === VIRTUAL_ID) return RESOLVED_ID;
+    },
+    load(id: string) {
+      if (id === RESOLVED_ID) {
+        return `
+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 type { KaraokeConfig, ResolvedModules, ResolvedLayout, RegionComponent } from './types.js';

package/src/layouts/Base.astro

@@ -0,0 +1,73 @@
+---
+import '@theme/styles.css';
+import RegionRenderer from '../components/RegionRenderer.astro';
+import { resolvedModules, resolvedLayout } from 'virtual:karaoke-cms/config';
+import { SITE_TITLE } from '../consts';
+
+interface Props {
+  title: string;
+  description?: string;
+  type?: 'website' | 'article';
+}
+
+const { title, description, type = 'website' } = Astro.props;
+const canonicalUrl = Astro.url.href;
+const layout = resolvedLayout;
+const modules = resolvedModules;
+const searchEnabled = modules.search.enabled;
+
+const hasLeft  = Astro.slots.has('left')  || layout.regions.left.components.length  > 0;
+const hasRight = Astro.slots.has('right') || layout.regions.right.components.length > 0;
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="icon" href="/favicon.ico" />
+    <meta name="generator" content={Astro.generator} />
+    <title>{title === SITE_TITLE ? title : `${title} — ${SITE_TITLE}`}</title>
+    {description && <meta name="description" content={description} />}
+    <meta property="og:title" content={title} />
+    <meta property="og:type" content={type} />
+    <meta property="og:url" content={canonicalUrl} />
+    {description && <meta property="og:description" content={description} />}
+    <meta name="twitter:card" content="summary" />
+    <link rel="alternate" type="application/rss+xml" title={SITE_TITLE} href="/rss.xml" />
+  </head>
+  <body>
+    <header>
+      <div class="header-inner">
+        <slot name="top">
+          <RegionRenderer components={layout.regions.top.components} {searchEnabled} />
+        </slot>
+      </div>
+    </header>
+    <div class:list={['page-body', { 'has-left': hasLeft, 'has-right': hasRight }]}>
+      {hasLeft && (
+        <aside class="region-left">
+          <slot name="left">
+            <RegionRenderer components={layout.regions.left.components} {searchEnabled} />
+          </slot>
+        </aside>
+      )}
+      <main>
+        <slot />
+      </main>
+      {hasRight && (
+        <aside class="region-right">
+          <slot name="right">
+            <RegionRenderer components={layout.regions.right.components} {searchEnabled} />
+          </slot>
+        </aside>
+      )}
+    </div>
+    <footer>
+      <slot name="bottom">
+        <RegionRenderer components={layout.regions.bottom.components} {searchEnabled} />
+      </slot>
+    </footer>
+  </body>
+</html>

package/src/modules/comments/Comments.astro

@@ -0,0 +1,44 @@
+---
+// Comments.astro — Giscus GitHub Discussions comments widget
+//
+// Props mirror the Giscus config fields in KaraokeConfig.
+// Rendered only when comments.enabled is true and repo is set.
+interface Props {
+  repo: string;
+  repoId: string;
+  category: string;
+  categoryId: string;
+}
+
+const { repo, repoId, category, categoryId } = Astro.props;
+---
+
+<div class="comments">
+  <script
+    define:vars={{ repo, repoId, category, categoryId }}
+  >
+    // define:vars injects repo/repoId/category/categoryId as const locals.
+    // We build the Giscus <script> tag dynamically so Astro doesn't try to
+    // process the external Giscus URL as an internal module.
+    // Store parent reference immediately — document.currentScript is nulled after async gaps.
+    const _parent = document.currentScript?.parentElement;
+    if (repo && repoId) {
+      const s = document.createElement('script');
+      s.src = 'https://giscus.app/client.js';
+      s.setAttribute('data-repo', repo);
+      s.setAttribute('data-repo-id', repoId);
+      s.setAttribute('data-category', category);
+      s.setAttribute('data-category-id', categoryId);
+      s.setAttribute('data-mapping', 'pathname');
+      s.setAttribute('data-strict', '0');
+      s.setAttribute('data-reactions-enabled', '1');
+      s.setAttribute('data-emit-metadata', '0');
+      s.setAttribute('data-input-position', 'bottom');
+      s.setAttribute('data-theme', 'preferred_color_scheme');
+      s.setAttribute('data-lang', 'en');
+      s.setAttribute('crossorigin', 'anonymous');
+      s.async = true;
+      _parent?.appendChild(s);
+    }
+  </script>
+</div>

package/src/modules/comments/index.ts

@@ -0,0 +1 @@
+export const id = 'comments';

package/src/modules/search/Search.astro

@@ -0,0 +1,32 @@
+---
+// Search.astro — Pagefind full-text search UI
+//
+// Pagefind index is only built post-`astro build` (not in dev mode).
+// We probe for the index file client-side and initialize only when present,
+// so `npm run dev` silently shows nothing rather than a 404 cascade.
+---
+
+<div id="search"></div>
+
+<script>
+  async function initSearch() {
+    // Pagefind won't exist in dev mode — probe before initialising
+    const probe = await fetch('/pagefind/pagefind-ui.js', { method: 'HEAD' }).catch(() => null);
+    if (!probe?.ok) return;
+
+    const link = document.createElement('link');
+    link.rel = 'stylesheet';
+    link.href = '/pagefind/pagefind-ui.css';
+    document.head.appendChild(link);
+
+    const script = document.createElement('script');
+    script.src = '/pagefind/pagefind-ui.js';
+    script.onload = () => {
+      // @ts-ignore — PagefindUI loaded by the external script above
+      new window.PagefindUI({ element: '#search', showSubResults: true });
+    };
+    document.head.appendChild(script);
+  }
+
+  initSearch();
+</script>

package/src/modules/search/index.ts

@@ -0,0 +1 @@
+export const id = 'search';

package/src/pages/404.astro

@@ -0,0 +1,14 @@
+---
+import Base from '../layouts/Base.astro';
+import { SITE_TITLE } from '../consts';
+---
+
+<Base title={`Page not found — ${SITE_TITLE}`}>
+  <div class="post-header">
+    <h1>Page not found</h1>
+    <p class="post-meta">The page you're looking for doesn't exist or hasn't been published.</p>
+  </div>
+  <div class="prose">
+    <p><a href="/">Go home →</a></p>
+  </div>
+</Base>

package/src/pages/blog/[slug].astro

@@ -0,0 +1,66 @@
+---
+import { getCollection, render } from 'astro:content';
+import Base from '../../layouts/Base.astro';
+import ModuleLoader from '../../components/ModuleLoader.astro';
+import { SITE_TITLE } from '../../consts';
+
+export async function getStaticPaths() {
+  const posts = await getCollection('blog', ({ data }) => data.publish === true);
+  return posts.map(entry => ({
+    params: { slug: entry.id },
+    props: { entry },
+  }));
+}
+
+const { entry } = Astro.props;
+const { Content } = await render(entry);
+
+// Resolve related entries by ID across both collections
+const relatedIds = entry.data.related ?? [];
+const related = relatedIds.length > 0
+  ? (await Promise.all([
+      getCollection('blog', ({ data }) => data.publish === true),
+      getCollection('docs', ({ data }) => data.publish === true),
+    ]))
+    .flat()
+    .filter(e => relatedIds.includes(e.id))
+  : [];
+---
+
+<Base title={`${entry.data.title} — ${SITE_TITLE}`} description={entry.data.description} type="article">
+  <article>
+    <div class="post-header">
+      <h1>{entry.data.title}</h1>
+      <div class="post-meta">
+        {entry.data.date && <span>{entry.data.date.toISOString().slice(0, 10)}</span>}
+        {entry.data.author && entry.data.date && <span> · </span>}
+        {entry.data.author && (
+          <span>{Array.isArray(entry.data.author) ? entry.data.author.join(' · ') : entry.data.author}</span>
+        )}
+        {entry.data.reading_time && <span> · {entry.data.reading_time} min read</span>}
+      </div>
+    </div>
+    <div class="prose">
+      <Content />
+    </div>
+    <div class="post-footer">
+      {entry.data.tags && entry.data.tags.length > 0 && (
+        <div class="post-tags">
+          {entry.data.tags.map(tag => <a href={`/tags/${tag}`} class="tag">#{tag}</a>)}
+        </div>
+      )}
+      {related.length > 0 && (
+        <div class="related-posts">
+          <p class="related-label">Related</p>
+          <ul>
+            {related.map(r => (
+              <li><a href={`/${r.collection}/${r.id}`}>{r.data.title}</a></li>
+            ))}
+          </ul>
+        </div>
+      )}
+      <a href="/blog">← Blog</a>
+    </div>
+  </article>
+  <ModuleLoader comments={entry.data.comments} />
+</Base>

package/src/pages/blog/index.astro

@@ -0,0 +1,31 @@
+---
+import { getCollection } from 'astro:content';
+import Base from '../../layouts/Base.astro';
+import { SITE_TITLE } from '../../consts';
+
+const posts = (await getCollection('blog', ({ data }) => data.publish === true))
+  .sort((a, b) => (b.data.date?.valueOf() ?? 0) - (a.data.date?.valueOf() ?? 0));
+---
+
+<Base title={`Blog — ${SITE_TITLE}`}>
+  <div class="listing-header">
+    <h1>Blog</h1>
+  </div>
+  {posts.length > 0 ? (
+    <ul class="post-list">
+      {posts.map(post => (
+        <li>
+          {post.data.date && (
+            <span class="post-date">{post.data.date.toISOString().slice(0, 10)}</span>
+          )}
+          <a href={`/blog/${post.id}`}>{post.data.title}</a>
+        </li>
+      ))}
+    </ul>
+  ) : (
+    <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>
+    </div>
+  )}
+</Base>