@karaoke-cms/module-blog 0.9.7 → 0.10.3

package/README.md

@@ -48,33 +48,58 @@ All routes are relative to `mount`:
 
 ```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
+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 path, absolute path, URL,
+                                      #   or Obsidian wiki link: "[[hero.jpg]]"
+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
 ---
 ```
 
+### `featured_image` formats
+
+All of the following work in `featured_image`:
+
+```yaml
+featured_image: "./images/hero.jpg"          # relative to the note
+featured_image: "/blog/hero.jpg"             # vault-absolute path
+featured_image: "https://example.com/x.jpg"  # remote URL
+featured_image: "[[hero.jpg]]"               # Obsidian wiki link — resolved via vault lookup
+```
+
+When using a wiki link, the image is served from `/media/` during dev and copied to `dist/media/` at build.
+
 ## 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 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';
 ```
 
+All three components call `resolveWikiImage()` internally, so wiki-linked featured images render correctly in list views without any extra work.
+
 ## 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.10.3
+
+No user-facing changes in this release.
+
+## What's new in 0.10.0
+
+- **`[[wiki link]]` in `featured_image`** — `featured_image: "[[hero.jpg]]"` now works in post cards, the featured hero card, and the individual post page; images are resolved via vault path lookup and served from `/media/`
+- **Blog list page** — `/blog` now has a dedicated list page separate from the post template, fixing a route conflict with the theme-default fallback
+
 ## 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

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@karaoke-cms/module-blog",
   "type": "module",
-  "version": "0.9.7",
+  "version": "0.10.3",
   "description": "Blog module for karaoke-cms — posts, tags, RSS",
   "main": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
     "./schema": "./src/schema.ts",
+    "./pages/list": "./src/pages/list.astro",
     "./pages/post": "./src/pages/post.astro",
     "./pages/page": "./src/pages/page/[page].astro",
     "./components/FeaturedPost": "./src/components/FeaturedPost.astro",
@@ -27,13 +28,15 @@
   },
   "peerDependencies": {
     "astro": ">=6.0.0",
-    "@karaoke-cms/astro": "^0.9.7"
+    "@karaoke-cms/contracts": "^0.10.3"
   },
   "devDependencies": {
-    "@karaoke-cms/astro": "workspace:*",
-    "astro": "^6.0.8"
+    "astro": "^6.0.8",
+    "vitest": "^4.1.1",
+    "@karaoke-cms/astro": "0.10.3",
+    "@karaoke-cms/contracts": "0.10.3"
   },
   "scripts": {
-    "test": "echo \"Stub — no tests\""
+    "test": "vitest run test/blog-factory.test.js"
   }
-}
+}

package/src/components/FeaturedPost.astro

@@ -1,5 +1,6 @@
 ---
 import type { CollectionEntry } from 'astro:content';
+import { resolveWikiImage } from '@karaoke-cms/astro';
 
 interface Props {
   post: CollectionEntry<'blog'>;
@@ -13,7 +14,7 @@ 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" />
+      <img src={resolveWikiImage(post.data.featured_image)} alt={post.data.title} class="blog-featured-image" />
     </a>
   )}
   <div class="blog-card-body">

package/src/components/PaginatedPostList.astro

@@ -1,6 +1,7 @@
 ---
 import type { CollectionEntry } from 'astro:content';
 import FeaturedPost from './FeaturedPost.astro';
+import { resolveWikiImage } from '@karaoke-cms/astro';
 
 interface Props {
   posts: CollectionEntry<'blog'>[];
@@ -22,7 +23,7 @@ const listPosts = featuredPost ? posts.slice(1) : posts;
     <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" />
+          <img src={resolveWikiImage(post.data.featured_image)} alt={post.data.title} class="blog-featured-image" />
         </a>
       )}
       <h2 class="blog-card-title">

package/src/css-contract.ts

@@ -1,29 +1,34 @@
+import type { CssContract } from '@karaoke-cms/contracts';
+
 /**
  * CSS class names the blog module promises to use in its markup.
  * Themes implement these classes to style the blog.
+ *
+ * `required: true`  — the theme MUST implement this class.
+ * `required: false` — optional / progressive enhancement.
  */
-export const cssContract = [
+export const cssContract: CssContract = {
   // List / card layout
-  'blog-list',
-  'blog-card',
-  'blog-card-title',
-  'blog-card-meta',
-  'blog-card-description',
+  'blog-list':             { description: 'Post list page wrapper',              required: true },
+  'blog-card':             { description: 'Individual post card in list',         required: true },
+  'blog-card-title':       { description: 'Post title inside a card',             required: true },
+  'blog-card-meta':        { description: 'Date/author meta row on a card',       required: false },
+  'blog-card-description': { description: 'Excerpt / description on a card',      required: false },
   // Featured post
-  'blog-featured-post',
-  'blog-featured-image',
+  'blog-featured-post':    { description: 'Featured post hero block',             required: false },
+  'blog-featured-image':   { description: 'Hero image inside featured post',      required: false },
   // Post page
-  'blog-post',
-  'blog-post-title',
-  'blog-post-meta',
+  'blog-post':             { description: 'Individual post article wrapper',      required: true },
+  'blog-post-title':       { description: 'Post title on the post page',          required: true },
+  'blog-post-meta':        { description: 'Date/author meta on the post page',    required: false },
   // Tags
-  'blog-tag',
-  'blog-tag-list',
+  'blog-tag':              { description: 'Tag chip on card or post page',        required: false },
+  'blog-tag-list':         { description: 'Wrapper around a list of tag chips',   required: false },
   // Pagination
-  'blog-pagination',
-  'blog-pagination-prev',
-  'blog-pagination-next',
-  'blog-pagination-current',
+  'blog-pagination':       { description: 'Pagination controls wrapper',          required: false },
+  'blog-pagination-prev':  { description: 'Previous page link',                   required: false },
+  'blog-pagination-next':  { description: 'Next page link',                       required: false },
+  'blog-pagination-current': { description: 'Current page indicator',            required: false },
   // Sidebar
-  'blog-sidebar-recent',
-] as const;
+  'blog-sidebar-recent':   { description: 'Recent posts sidebar widget',          required: false },
+};

package/src/index.ts

@@ -1,4 +1,4 @@
-import { defineModule } from '@karaoke-cms/astro';
+import { defineModule } from '@karaoke-cms/contracts';
 import { fileURLToPath } from 'url';
 import { join } from 'path';
 import { cssContract } from './css-contract.js';
@@ -28,8 +28,9 @@ export const blog = defineModule({
   defaultCssPath: join(_srcDir, 'styles', 'blog.css'),
 
   routes: (mount) => [
-    { pattern: `${mount}/[slug]`,         entrypoint: '@karaoke-cms/module-blog/pages/post' },
-    { pattern: `${mount}/page/[page]`,    entrypoint: '@karaoke-cms/module-blog/pages/page' },
+    { pattern: mount,                      entrypoint: '@karaoke-cms/module-blog/pages/list' },
+    { pattern: `${mount}/[slug]`,          entrypoint: '@karaoke-cms/module-blog/pages/post' },
+    { pattern: `${mount}/page/[page]`,     entrypoint: '@karaoke-cms/module-blog/pages/page' },
   ],
 
   menuEntries: (mount, id) => [
@@ -40,7 +41,8 @@ export const blog = defineModule({
   scaffoldPages: (mount) => {
     const mountDir = mount.replace(/^\//, '') || 'blog';
     return [
-      { src: join(_srcDir, 'pages', 'post.astro'),          dest: `${mountDir}/[slug].astro` },
+      { src: join(_srcDir, 'pages', 'list.astro'),            dest: `${mountDir}/index.astro` },
+      { 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/list.astro

@@ -0,0 +1,26 @@
+---
+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;
+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));
+const posts = allPosts.slice(0, PAGE_SIZE);
+---
+
+<DefaultPage title={`Blog — ${siteTitle}`}>
+  {posts.length > 0 ? (
+    <PaginatedPostList posts={posts} mount={blogMount} currentPage={1} totalPages={totalPages} />
+  ) : (
+    <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>
+  )}
+  <RecentPosts mount={blogMount} slot="right" />
+</DefaultPage>

package/src/pages/post.astro

@@ -4,6 +4,7 @@ import DefaultPage from '@karaoke-cms/astro/layouts/DefaultPage.astro';
 import ModuleLoader from '@karaoke-cms/astro/components/ModuleLoader.astro';
 import RecentPosts from '@karaoke-cms/module-blog/components/RecentPosts';
 import { siteTitle, blogMount } from 'virtual:karaoke-cms/config';
+import { resolveWikiImage } from '@karaoke-cms/astro';
 
 export async function getStaticPaths() {
   const posts = await getCollection('blog', ({ data }) => data.publish === true);
@@ -47,7 +48,7 @@ const related = relatedIds.length > 0
       )}
     </div>
     {entry.data.featured_image && (
-      <img src={entry.data.featured_image} alt={entry.data.title} class="blog-featured-image" />
+      <img src={resolveWikiImage(entry.data.featured_image)} alt={entry.data.title} class="blog-featured-image" />
     )}
     <div class="prose blog-post">
       <Content />