@karaoke-cms/module-blog 0.9.3 → 0.9.5

package/README.md

@@ -0,0 +1,85 @@
+# @karaoke-cms/module-blog
+
+Blog module for karaoke-cms — paginated post listing, individual post pages, tag filtering, pagination, and an RSS link in the footer nav.
+
+## Installation
+
+```bash
+npm install @karaoke-cms/module-blog
+```
+
+## Usage
+
+```ts
+// karaoke.config.ts
+import { defineConfig } from '@karaoke-cms/astro';
+import { loadEnv } from '@karaoke-cms/astro/env';
+import { blog } from '@karaoke-cms/module-blog';
+import { themeDefault } from '@karaoke-cms/theme-default';
+
+const env = loadEnv(new URL('.', import.meta.url));
+
+export default defineConfig({
+  vault: env.KARAOKE_VAULT,
+  theme: themeDefault({
+    implements: [blog({ mount: '/blog' })],
+  }),
+});
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `mount` | `string` | `'/blog'` | URL prefix for all blog routes |
+| `enabled` | `boolean` | `true` | Set `false` to disable the module entirely |
+
+## Routes
+
+All routes are relative to `mount`:
+
+| Pattern | Description |
+|---------|-------------|
+| `{mount}` | Paginated post list |
+| `{mount}/[slug]` | Single post page |
+| `{mount}/page/[page]` | Overflow pagination pages |
+
+## Frontmatter
+
+```yaml
+---
+title: "My Post"               # required
+publish: true                  # required to appear on site
+date: 2026-01-15               # optional — YYYY-MM-DD
+author: "Name"                 # optional — string or array
+featured_image: "img/hero.jpg" # optional — relative to vault
+description: "..."             # optional — OG tags, RSS, AI-enriched
+tags: [writing, tutorial]      # optional — powers /tags pages
+reading_time: 5                # optional — AI-enriched, minutes
+related: [slug-a, slug-b]      # optional — AI-enriched, slugs
+comments: true                 # optional — per-post Giscus override
+---
+```
+
+## Components
+
+The module ships reusable components you can import in your own pages:
+
+```ts
+import FeaturedPost    from '@karaoke-cms/module-blog/components/FeaturedPost';
+import RecentPosts     from '@karaoke-cms/module-blog/components/RecentPosts';
+import PaginatedPostList from '@karaoke-cms/module-blog/components/PaginatedPostList';
+```
+
+## Scaffold
+
+On first `npm run dev`, the module copies starter page files into your project's `src/pages/{mountDir}/`. You can edit these files to customise the layout without modifying the npm package.
+
+## What's new in 0.9.5
+
+- **Full page scaffold** — on first dev run, `list.astro`, `[slug].astro`, and `page/[page].astro` are copied to your `src/pages/blog/` so you can customise them
+- **`FeaturedPost`, `RecentPosts`, `PaginatedPostList` components** exported for use in custom pages
+- **30 demo posts** included in new project vaults so the site looks populated on first visit
+- **Default CSS** (`src/styles/blog.css`) copied on first dev run and auto-imported into `global.css`
+- **`enabled` flag** — `blog({ mount: '/blog', enabled: false })` disables the module without removing it from config
+- **Fixed zod import** — `zod` now correctly declared as a dependency (was missing from lockfile)

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@karaoke-cms/module-blog",
   "type": "module",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "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"
+    "./schema": "./src/schema.ts",
+    "./pages/post": "./src/pages/post.astro",
+    "./pages/page": "./src/pages/page/[page].astro",
+    "./components/FeaturedPost": "./src/components/FeaturedPost.astro",
+    "./components/RecentPosts": "./src/components/RecentPosts.astro",
+    "./components/PaginatedPostList": "./src/components/PaginatedPostList.astro"
   },
   "files": [
     "src/"
@@ -18,9 +22,12 @@
     "blog",
     "karaoke-cms"
   ],
+  "dependencies": {
+    "zod": "^4.0.0"
+  },
   "peerDependencies": {
     "astro": ">=6.0.0",
-    "@karaoke-cms/astro": "^0.9.2"
+    "@karaoke-cms/astro": "^0.9.5"
   },
   "devDependencies": {
     "@karaoke-cms/astro": "workspace:*",

package/src/components/FeaturedPost.astro

@@ -0,0 +1,32 @@
+---
+import type { CollectionEntry } from 'astro:content';
+
+interface Props {
+  post: CollectionEntry<'blog'>;
+  mount: string;
+}
+
+const { post, mount } = Astro.props;
+const href = `${mount}/${post.id}`;
+---
+
+<article class="blog-card blog-featured-post">
+  {post.data.featured_image && (
+    <a href={href} tabindex="-1" aria-hidden="true">
+      <img src={post.data.featured_image} alt={post.data.title} class="blog-featured-image" />
+    </a>
+  )}
+  <div class="blog-card-body">
+    <h2 class="blog-card-title"><a href={href}>{post.data.title}</a></h2>
+    <div class="blog-card-meta">
+      {post.data.date && <span>{post.data.date.toISOString().slice(0, 10)}</span>}
+      {post.data.reading_time && <span> · {post.data.reading_time} min read</span>}
+    </div>
+    {post.data.description && <p class="blog-card-description">{post.data.description}</p>}
+    {post.data.tags && post.data.tags.length > 0 && (
+      <div class="blog-tag-list">
+        {post.data.tags.map(tag => <a href={`/tags/${tag}`} class="blog-tag">#{tag}</a>)}
+      </div>
+    )}
+  </div>
+</article>

package/src/components/PaginatedPostList.astro

@@ -0,0 +1,54 @@
+---
+import type { CollectionEntry } from 'astro:content';
+import FeaturedPost from './FeaturedPost.astro';
+
+interface Props {
+  posts: CollectionEntry<'blog'>[];
+  mount: string;
+  currentPage: number;
+  totalPages: number;
+  /** Show the first post as a featured hero card. Only on page 1. Defaults to true. */
+  showFeatured?: boolean;
+}
+
+const { posts, mount, currentPage, totalPages, showFeatured = true } = Astro.props;
+const featuredPost = showFeatured && currentPage === 1 ? posts[0] : undefined;
+const listPosts = featuredPost ? posts.slice(1) : posts;
+---
+
+<div class="blog-list">
+  {featuredPost && <FeaturedPost post={featuredPost} mount={mount} />}
+  {listPosts.map(post => (
+    <article class="blog-card">
+      {post.data.featured_image && (
+        <a href={`${mount}/${post.id}`} tabindex="-1" aria-hidden="true">
+          <img src={post.data.featured_image} alt={post.data.title} class="blog-featured-image" />
+        </a>
+      )}
+      <h2 class="blog-card-title">
+        <a href={`${mount}/${post.id}`}>{post.data.title}</a>
+      </h2>
+      <div class="blog-card-meta">
+        {post.data.date && <span>{post.data.date.toISOString().slice(0, 10)}</span>}
+        {post.data.reading_time && <span> · {post.data.reading_time} min read</span>}
+      </div>
+      {post.data.description && <p class="blog-card-description">{post.data.description}</p>}
+      {post.data.tags && post.data.tags.length > 0 && (
+        <div class="blog-tag-list">
+          {post.data.tags.map(tag => <a href={`/tags/${tag}`} class="blog-tag">#{tag}</a>)}
+        </div>
+      )}
+    </article>
+  ))}
+  {totalPages > 1 && (
+    <nav class="blog-pagination" aria-label="Blog pagination">
+      {currentPage > 1 && (
+        <a href={currentPage === 2 ? mount : `${mount}/page/${currentPage - 1}`} class="blog-pagination-prev">← Previous</a>
+      )}
+      <span class="blog-pagination-current">Page {currentPage} of {totalPages}</span>
+      {currentPage < totalPages && (
+        <a href={`${mount}/page/${currentPage + 1}`} class="blog-pagination-next">Next →</a>
+      )}
+    </nav>
+  )}
+</div>

package/src/components/RecentPosts.astro

@@ -0,0 +1,33 @@
+---
+import { getCollection } from 'astro:content';
+
+interface Props {
+  mount: string;
+  /** Max posts to show. Defaults to 5. */
+  limit?: number;
+  /** Post ID to exclude (typically the currently viewed post). */
+  exclude?: string;
+}
+
+const { mount, limit = 5, exclude } = Astro.props;
+const posts = (await getCollection('blog', ({ data }) => data.publish === true))
+  .sort((a, b) => (b.data.date?.valueOf() ?? 0) - (a.data.date?.valueOf() ?? 0))
+  .filter(p => p.id !== exclude)
+  .slice(0, limit);
+---
+
+{posts.length > 0 && (
+  <div class="blog-sidebar-recent">
+    <h3>Recent Posts</h3>
+    <ul class="blog-list">
+      {posts.map(post => (
+        <li class="blog-card">
+          <a href={`${mount}/${post.id}`} class="blog-card-title">{post.data.title}</a>
+          {post.data.date && (
+            <span class="blog-card-meta">{post.data.date.toISOString().slice(0, 10)}</span>
+          )}
+        </li>
+      ))}
+    </ul>
+  </div>
+)}

package/src/css-contract.ts

@@ -3,13 +3,27 @@
  * Themes implement these classes to style the blog.
  */
 export const cssContract = [
+  // List / card layout
   'blog-list',
   'blog-card',
   'blog-card-title',
   'blog-card-meta',
+  'blog-card-description',
+  // Featured post
+  'blog-featured-post',
+  'blog-featured-image',
+  // Post page
   'blog-post',
   'blog-post-title',
   'blog-post-meta',
+  // Tags
   'blog-tag',
   'blog-tag-list',
+  // Pagination
+  'blog-pagination',
+  'blog-pagination-prev',
+  'blog-pagination-next',
+  'blog-pagination-current',
+  // Sidebar
+  'blog-sidebar-recent',
 ] as const;

package/src/index.ts

@@ -1,35 +1,47 @@
 import { defineModule } from '@karaoke-cms/astro';
+import { fileURLToPath } from 'url';
+import { join } from 'path';
 import { cssContract } from './css-contract.js';
 
-export { blogSchema } from './schema.js';
 export { cssContract } from './css-contract.js';
+// blogSchema is exported from '@karaoke-cms/module-blog/schema' to avoid
+// pulling zod into the config-loading context.
+
+const _srcDir = fileURLToPath(new URL('.', import.meta.url));
 
 /**
- * Blog module — posts, listing, and tag pages.
+ * Blog module — posts, listing, pagination, and tag pages.
  *
  * @example
  * // karaoke.config.ts
  * import { blog } from '@karaoke-cms/module-blog';
+ * import { themeDefault } from '@karaoke-cms/theme-default';
  * export default defineConfig({
  *   modules: [blog({ mount: '/blog' })],
- *   theme: themeDefault({ implements: [blog({ mount: '/blog' })] }),
+ *   theme: themeDefault(),
  * });
  */
 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,
+  defaultCssPath: join(_srcDir, 'styles', 'blog.css'),
 
   routes: (mount) => [
-    { pattern: mount || '/',          entrypoint: '@karaoke-cms/module-blog/pages/list' },
-    { pattern: `${mount}/[slug]`,     entrypoint: '@karaoke-cms/module-blog/pages/post' },
+    { pattern: `${mount}/[slug]`,         entrypoint: '@karaoke-cms/module-blog/pages/post' },
+    { pattern: `${mount}/page/[page]`,    entrypoint: '@karaoke-cms/module-blog/pages/page' },
   ],
 
   menuEntries: (mount, id) => [
-    { id,             name: 'Blog', path: '/',        section: 'main',   weight: 10 },
-    { id: `${id}-rss`, name: 'RSS',  path: '/rss.xml', section: 'footer', weight: 10 },
+    { id,              name: 'Blog', path: mount || '/', section: 'main',   weight: 10 },
+    { id: `${id}-rss`, name: 'RSS',  path: '/rss.xml',  section: 'footer', weight: 10 },
   ],
+
+  scaffoldPages: (mount) => {
+    const mountDir = mount.replace(/^\//, '') || 'blog';
+    return [
+      { src: join(_srcDir, 'pages', 'post.astro'),          dest: `${mountDir}/[slug].astro` },
+      { src: join(_srcDir, 'pages', 'page', '[page].astro'), dest: `${mountDir}/page/[page].astro` },
+    ];
+  },
 });

package/src/pages/page/[page].astro

@@ -0,0 +1,41 @@
+---
+import { getCollection } from 'astro:content';
+import DefaultPage from '@karaoke-cms/astro/layouts/DefaultPage.astro';
+import PaginatedPostList from '@karaoke-cms/module-blog/components/PaginatedPostList';
+import RecentPosts from '@karaoke-cms/module-blog/components/RecentPosts';
+import { siteTitle, blogMount } from 'virtual:karaoke-cms/config';
+
+const PAGE_SIZE = 10;
+
+export async function getStaticPaths() {
+  const PAGE_SIZE = 10;
+  const allPosts = (await getCollection('blog', ({ data }) => data.publish === true))
+    .sort((a, b) => (b.data.date?.valueOf() ?? 0) - (a.data.date?.valueOf() ?? 0));
+  const totalPages = Math.max(1, Math.ceil(allPosts.length / PAGE_SIZE));
+
+  return Array.from({ length: Math.max(0, totalPages - 1) }, (_, i) => {
+    const page = i + 2;
+    return {
+      params: { page: String(page) },
+      props: {
+        posts: allPosts.slice((page - 1) * PAGE_SIZE, page * PAGE_SIZE),
+        currentPage: page,
+        totalPages,
+      },
+    };
+  });
+}
+
+const { posts, currentPage, totalPages } = Astro.props;
+---
+
+<DefaultPage title={`Blog — Page ${currentPage} — ${siteTitle}`}>
+  <PaginatedPostList
+    posts={posts}
+    mount={blogMount}
+    currentPage={currentPage}
+    totalPages={totalPages}
+    showFeatured={false}
+  />
+  <RecentPosts mount={blogMount} slot="right" />
+</DefaultPage>

package/src/pages/post.astro

@@ -1,10 +1,9 @@
 ---
-// 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';
+import RecentPosts from '@karaoke-cms/module-blog/components/RecentPosts';
+import { siteTitle, blogMount } from 'virtual:karaoke-cms/config';
 
 export async function getStaticPaths() {
   const posts = await getCollection('blog', ({ data }) => data.publish === true);
@@ -31,9 +30,9 @@ const related = relatedIds.length > 0
 
 <DefaultPage title={`${entry.data.title} — ${siteTitle}`} description={entry.data.description} type="article">
   <article>
-    <div class="post-header">
+    <div class="blog-post-title">
       <h1>{entry.data.title}</h1>
-      <div class="post-meta">
+      <div class="blog-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 && (
@@ -41,16 +40,19 @@ const related = relatedIds.length > 0
         )}
         {entry.data.reading_time && <span> · {entry.data.reading_time} min read</span>}
       </div>
+      {entry.data.tags && entry.data.tags.length > 0 && (
+        <div class="blog-tag-list">
+          {entry.data.tags.map(tag => <a href={`/tags/${tag}`} class="blog-tag">#{tag}</a>)}
+        </div>
+      )}
     </div>
-    <div class="prose">
+    {entry.data.featured_image && (
+      <img src={entry.data.featured_image} alt={entry.data.title} class="blog-featured-image" />
+    )}
+    <div class="prose blog-post">
       <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>
@@ -61,8 +63,9 @@ const related = relatedIds.length > 0
           </ul>
         </div>
       )}
-      <a href="/blog">← Blog</a>
+      <a href={blogMount}>← Blog</a>
     </div>
   </article>
   <ModuleLoader comments={entry.data.comments} />
+  <RecentPosts mount={blogMount} exclude={entry.id} slot="right" />
 </DefaultPage>

package/src/schema.ts

@@ -14,6 +14,8 @@ export const blogSchema = z.object({
   description:  z.string().optional(),
   reading_time: z.number().optional(),
   related:      z.array(z.string()).optional(),
+  // media
+  featured_image: z.string().optional(),
   // per-post comments override
   comments:     z.boolean().optional().default(true),
 });

package/src/styles/blog.css

@@ -0,0 +1,135 @@
+/* Blog module default styles — copy of this file lives at src/styles/blog.css */
+
+.blog-list {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 1.5rem;
+}
+
+.blog-card {
+  padding: 1rem 0;
+  border-bottom: 1px solid var(--color-border, #e5e7eb);
+}
+
+.blog-card:last-child {
+  border-bottom: none;
+}
+
+.blog-card-title {
+  font-size: 1.125rem;
+  font-weight: 600;
+  margin: 0 0 0.25rem;
+}
+
+.blog-card-title a {
+  text-decoration: none;
+  color: inherit;
+}
+
+.blog-card-title a:hover {
+  text-decoration: underline;
+}
+
+.blog-card-meta {
+  font-size: 0.875rem;
+  opacity: 0.65;
+  margin-bottom: 0.5rem;
+}
+
+.blog-card-description {
+  margin: 0.5rem 0 0;
+  font-size: 0.9375rem;
+  line-height: 1.6;
+}
+
+/* Featured post */
+.blog-featured-post {
+  padding: 0 0 1.5rem;
+  margin-bottom: 0.5rem;
+  border-bottom: 2px solid var(--color-border, #e5e7eb);
+}
+
+.blog-featured-image {
+  width: 100%;
+  height: auto;
+  border-radius: 0.5rem;
+  display: block;
+  margin-bottom: 1rem;
+}
+
+/* Post page */
+.blog-post {
+  line-height: 1.75;
+}
+
+.blog-post-title h1 {
+  margin-bottom: 0.5rem;
+}
+
+.blog-post-meta {
+  font-size: 0.875rem;
+  opacity: 0.65;
+  margin-bottom: 1.5rem;
+}
+
+/* Tags */
+.blog-tag-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.375rem;
+  margin-top: 0.75rem;
+}
+
+.blog-tag {
+  font-size: 0.75rem;
+  padding: 0.125rem 0.5rem;
+  border-radius: 999px;
+  background: var(--color-tag-bg, #f3f4f6);
+  color: var(--color-tag-text, #374151);
+  text-decoration: none;
+}
+
+.blog-tag:hover {
+  background: var(--color-tag-bg-hover, #e5e7eb);
+}
+
+/* Pagination */
+.blog-pagination {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  margin-top: 2rem;
+  padding-top: 1rem;
+  border-top: 1px solid var(--color-border, #e5e7eb);
+}
+
+.blog-pagination-current {
+  font-size: 0.875rem;
+  opacity: 0.65;
+}
+
+/* Sidebar recent posts */
+.blog-sidebar-recent h3 {
+  font-size: 0.875rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  opacity: 0.65;
+  margin-bottom: 0.75rem;
+}
+
+.blog-sidebar-recent .blog-list {
+  gap: 0.75rem;
+}
+
+.blog-sidebar-recent .blog-card {
+  padding: 0;
+  border-bottom: none;
+}
+
+.blog-sidebar-recent .blog-card-title {
+  font-size: 0.9375rem;
+}

package/src/pages/list.astro

@@ -1,33 +0,0 @@
----
-// 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>