@karaoke-cms/module-blog 0.9.3

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@karaoke-cms/module-blog",
+  "type": "module",
+  "version": "0.9.3",
+  "description": "Blog module for karaoke-cms — posts, tags, RSS",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./pages/list": "./src/pages/list.astro",
+    "./pages/post": "./src/pages/post.astro"
+  },
+  "files": [
+    "src/"
+  ],
+  "keywords": [
+    "astro",
+    "cms",
+    "blog",
+    "karaoke-cms"
+  ],
+  "peerDependencies": {
+    "astro": ">=6.0.0",
+    "@karaoke-cms/astro": "^0.9.2"
+  },
+  "devDependencies": {
+    "@karaoke-cms/astro": "workspace:*",
+    "astro": "^6.0.8"
+  },
+  "scripts": {
+    "test": "echo \"Stub — no tests\""
+  }
+}

package/src/css-contract.ts

@@ -0,0 +1,15 @@
+/**
+ * CSS class names the blog module promises to use in its markup.
+ * Themes implement these classes to style the blog.
+ */
+export const cssContract = [
+  'blog-list',
+  'blog-card',
+  'blog-card-title',
+  'blog-card-meta',
+  'blog-post',
+  'blog-post-title',
+  'blog-post-meta',
+  'blog-tag',
+  'blog-tag-list',
+] as const;

package/src/index.ts

@@ -0,0 +1,35 @@
+import { defineModule } from '@karaoke-cms/astro';
+import { cssContract } from './css-contract.js';
+
+export { blogSchema } from './schema.js';
+export { cssContract } from './css-contract.js';
+
+/**
+ * Blog module — posts, listing, and tag pages.
+ *
+ * @example
+ * // karaoke.config.ts
+ * import { blog } from '@karaoke-cms/module-blog';
+ * export default defineConfig({
+ *   modules: [blog({ mount: '/blog' })],
+ *   theme: themeDefault({ implements: [blog({ mount: '/blog' })] }),
+ * });
+ */
+export const blog = defineModule({
+  id: 'blog',
+  cssContract,
+
+  // No default CSS — requires a theme implementation.
+  // Add defaultCss here once a bare/unstyled default exists.
+  defaultCss: undefined,
+
+  routes: (mount) => [
+    { pattern: mount || '/',          entrypoint: '@karaoke-cms/module-blog/pages/list' },
+    { pattern: `${mount}/[slug]`,     entrypoint: '@karaoke-cms/module-blog/pages/post' },
+  ],
+
+  menuEntries: (mount, id) => [
+    { id,             name: 'Blog', path: '/',        section: 'main',   weight: 10 },
+    { id: `${id}-rss`, name: 'RSS',  path: '/rss.xml', section: 'footer', weight: 10 },
+  ],
+});

package/src/pages/list.astro

@@ -0,0 +1,33 @@
+---
+// TODO: use mount path from virtual module once mount-aware routing is implemented.
+// For now, mount is assumed to be /blog.
+import { getCollection } from 'astro:content';
+import DefaultPage from '@karaoke-cms/astro/layouts/DefaultPage.astro';
+import { siteTitle } from 'virtual:karaoke-cms/config';
+
+const posts = (await getCollection('blog', ({ data }) => data.publish === true))
+  .sort((a, b) => (b.data.date?.valueOf() ?? 0) - (a.data.date?.valueOf() ?? 0));
+---
+
+<DefaultPage title={`Blog — ${siteTitle}`}>
+  <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 your vault's <code>blog/</code> folder and set <code>publish: true</code> in the frontmatter to make it appear here.</p>
+    </div>
+  )}
+</DefaultPage>

package/src/pages/post.astro

@@ -0,0 +1,68 @@
+---
+// TODO: use mount path from virtual module once mount-aware routing is implemented.
+// For now, mount is assumed to be /blog.
+import { getCollection, render } from 'astro:content';
+import DefaultPage from '@karaoke-cms/astro/layouts/DefaultPage.astro';
+import ModuleLoader from '@karaoke-cms/astro/components/ModuleLoader.astro';
+import { siteTitle } from 'virtual:karaoke-cms/config';
+
+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))
+  : [];
+---
+
+<DefaultPage title={`${entry.data.title} — ${siteTitle}`} 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} />
+</DefaultPage>

package/src/schema.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+
+/**
+ * Frontmatter schema for blog posts.
+ * All fields except `title` are optional — posts validate before and after AI enrichment.
+ */
+export const blogSchema = z.object({
+  title:        z.string(),
+  publish:      z.boolean().optional().default(false),
+  date:         z.coerce.date().optional(),
+  author:       z.union([z.string(), z.array(z.string())]).optional(),
+  // v0.2 AI-enriched fields
+  tags:         z.array(z.string()).optional(),
+  description:  z.string().optional(),
+  reading_time: z.number().optional(),
+  related:      z.array(z.string()).optional(),
+  // per-post comments override
+  comments:     z.boolean().optional().default(true),
+});