@karaoke-cms/module-docs 0.9.7 → 0.10.3

package/README.md

@@ -49,19 +49,50 @@ All routes are relative to `mount`:
 
 ```yaml
 ---
-title: "Getting Started"       # 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, AI-enriched
-tags: [setup, guide]           # optional — AI-enriched
-reading_time: 3                # optional — AI-enriched, minutes
-related: [slug-a, slug-b]      # optional — AI-enriched, slugs
-comments: false                # optional — per-doc Giscus override (off by default)
+title: "Getting Started"              # 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, AI-enriched
+tags: [setup, guide]                  # optional — AI-enriched
+reading_time: 3                       # optional — AI-enriched, minutes
+related: [slug-a, slug-b]             # optional — AI-enriched, slugs
+comments: false                       # optional — per-doc Giscus override (off by default)
 ---
 ```
 
+### `featured_image` formats
+
+All of the following work in `featured_image`:
+
+```yaml
+featured_image: "./images/hero.jpg"          # relative to the note
+featured_image: "/docs/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.
+
+## What's new in 0.10.3
+
+- **Warning for `mount: '/'`** — calling `docs({ mount: '/' })` without an explicit `folder` now prints a warning, because the folder silently defaults to `"docs"` in this case. Pass `folder` explicitly to suppress it: `docs({ mount: '/', folder: 'docs' })`.
+
+## What's new in 0.10.2
+
+- **Multiple named docs sections** — call `docs()` multiple times with different `mount`, `folder`, and `label` values to create independent docs areas from separate vault folders.
+- **`folder` option** — map a docs instance to any vault subfolder (defaults to the mount path without the leading slash).
+- **`id` option** — override the Astro collection name (defaults to folder path, slashes replaced with hyphens).
+- **`label` option** — set a human-readable section title shown in navigation and page headings (defaults to id in Title Case).
+- **Section switcher** — when two or more sections are active, a nav row appears above the sidebar so readers can jump between sections.
+- **Auto-registered collections** — pass your full karaoke config to `makeCollections({ config })` in `content.config.ts` and every docs instance registers automatically. No manual changes needed when adding a second section.
+
+## What's new in 0.10.0
+
+- **`[[wiki link]]` in `featured_image`** — `featured_image: "[[hero.jpg]]"` now works on doc pages; images are resolved via vault path lookup and served from `/media/`
+
 ## What's new in 0.9.5
 
 - **`featured_image` support** added to the docs schema

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@karaoke-cms/module-docs",
   "type": "module",
-  "version": "0.9.7",
+  "version": "0.10.3",
   "description": "Docs module for karaoke-cms — documentation pages with sidebar navigation",
   "main": "./src/index.ts",
   "exports": {
@@ -23,13 +23,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/docs-factory.test.js"
   }
-}
+}

package/src/css-contract.ts

@@ -1,20 +1,30 @@
+import type { CssContract } from '@karaoke-cms/contracts';
+
 /**
  * CSS class names the docs module promises to use in its markup.
  * Themes implement these classes to style the docs section.
+ *
+ * `required: true`  — the theme MUST implement this class.
+ * `required: false` — optional / progressive enhancement.
  */
-export const cssContract = [
-  'docs-home',
-  'docs-home-list',
-  'docs-home-item',
-  'docs-list',
-  'docs-list-item',
-  'docs-article',
-  'docs-article-image',
-  'docs-article-title',
-  'docs-article-meta',
-  'docs-tag',
-  'docs-tag-list',
-  'docs-sidebar',
-  'docs-sidebar-list',
-  'docs-sidebar-item',
-] as const;
+export const cssContract: CssContract = {
+  // Home / overview
+  'docs-home':          { description: 'Docs home page wrapper',                   required: true },
+  'docs-home-list':     { description: 'List of doc links on the home page',        required: true },
+  'docs-home-item':     { description: 'Individual doc link on the home page',      required: true },
+  // Full list page
+  'docs-list':          { description: 'Full docs listing page wrapper',            required: false },
+  'docs-list-item':     { description: 'Individual row in the full docs list',      required: false },
+  // Article page
+  'docs-article':       { description: 'Individual doc article wrapper',            required: true },
+  'docs-article-image': { description: 'Featured image inside a doc article',       required: false },
+  'docs-article-title': { description: 'Doc article title',                         required: true },
+  'docs-article-meta':  { description: 'Date/author meta row on a doc article',     required: false },
+  // Tags
+  'docs-tag':           { description: 'Tag chip on doc card or article',           required: false },
+  'docs-tag-list':      { description: 'Wrapper around a list of doc tag chips',    required: false },
+  // Sidebar navigation
+  'docs-sidebar':       { description: 'Sidebar nav wrapper',                       required: true },
+  'docs-sidebar-list':  { description: 'List of nav links inside the sidebar',      required: true },
+  'docs-sidebar-item':  { description: 'Individual nav link in the sidebar',        required: true },
+};

package/src/index.ts

@@ -1,40 +1,84 @@
-import { defineModule } from '@karaoke-cms/astro';
+import type { ModuleInstance } from '@karaoke-cms/contracts';
 import { cssContract } from './css-contract.js';
 
 export { cssContract } from './css-contract.js';
 // docsSchema is exported from '@karaoke-cms/module-docs/schema' to avoid
 // pulling zod into the config-loading context.
 
+export interface DocsConfig {
+  /** Mount path for this docs section. Default: '/docs'. */
+  mount?: string;
+  /** Vault subfolder containing the docs markdown files. Default: mount path without leading slash. */
+  folder?: string;
+  /**
+   * Unique identifier for this docs instance. Used as the Astro collection name.
+   * Default: folder path with slashes replaced by hyphens.
+   */
+  id?: string;
+  /** Human-readable label shown in navigation and page titles. Default: id in Title Case. */
+  label?: string;
+  /** When false, this instance is excluded from the build. Default: true. */
+  enabled?: boolean;
+  layout?: string;
+  sidebarStyle?: string;
+}
+
 /**
  * Docs module — documentation pages with sidebar navigation.
  *
- * Publishes three routes:
- *   - `{mount}`       — home page listing all doc titles
- *   - `{mount}/list`  — standalone full docs list
- *   - `{mount}/[slug]` — individual doc with left-sidebar nav
+ * Returns a ModuleInstance that karaoke() uses to code-generate per-instance
+ * .astro page files and inject them as routes. Multiple instances may be
+ * configured to serve separate docs sections from different vault folders.
+ *
+ * Publishes three routes per instance:
+ *   - `{mount}`          — home page listing all doc titles
+ *   - `{mount}/list`     — standalone full docs list
+ *   - `{mount}/[slug]`   — individual doc with left-sidebar nav
  *
  * @example
- * // karaoke.config.ts
+ * // karaoke.config.ts — default section
  * import { docs } from '@karaoke-cms/module-docs';
  * export default defineConfig({
- *   modules: [docs({ mount: '/docs' })],
  *   theme: themeDefault({ implements: [docs({ mount: '/docs' })] }),
  * });
+ *
+ * @example
+ * // karaoke.config.ts — two independent sections
+ * export default defineConfig({
+ *   theme: themeDefault({ implements: [docs({ mount: '/docs' })] }),
+ *   modules: [docs({ mount: '/api-docs', folder: 'api-reference', label: 'API Reference' })],
+ * });
  */
-export const docs = defineModule({
-  id: 'docs',
-  cssContract,
-
-  // No default CSS — requires a theme implementation.
-  defaultCss: undefined,
-
-  routes: (mount) => [
-    { pattern: mount || '/docs',      entrypoint: '@karaoke-cms/module-docs/pages/home' },
-    { pattern: `${mount}/list`,       entrypoint: '@karaoke-cms/module-docs/pages/list' },
-    { pattern: `${mount}/[slug]`,     entrypoint: '@karaoke-cms/module-docs/pages/doc'  },
-  ],
-
-  menuEntries: (mount, id) => [
-    { id, name: 'Docs', path: mount, section: 'main', weight: 20 },
-  ],
-});
+export function docs(config: DocsConfig = {}): ModuleInstance {
+  const mount = (config.mount ?? '/docs').replace(/\/$/, '');
+  const rawFolder = mount.replace(/^\//, '');
+  if (config.folder === undefined && rawFolder === '') {
+    console.warn(
+      '[karaoke-cms] docs({ mount: \'/\' }): folder defaults to "docs". ' +
+      'Pass folder explicitly (e.g. docs({ mount: \'/\', folder: \'docs\' })) to suppress this warning.',
+    );
+  }
+  const folder = config.folder ?? (rawFolder || 'docs');
+  const id = config.id ?? (folder.replace(/\//g, '-') || 'docs');
+  const label = config.label ?? (id.charAt(0).toUpperCase() + id.slice(1).replace(/-/g, ' '));
+  return {
+    _type: 'module-instance',
+    id,
+    mount,
+    enabled: config.enabled ?? true,
+    collection: {
+      name: id,
+      folder,
+      label,
+      layout: config.layout ?? 'default',
+      sidebarStyle: config.sidebarStyle ?? 'tree',
+    },
+    // routes is empty — karaoke() generates per-instance pages via codegen
+    routes: [],
+    menuEntries: [{ id, name: label, path: mount, section: 'main', weight: 20 }],
+    cssContract,
+    hasDefaultCss: false,
+    defaultCssPath: undefined,
+    scaffoldPages: undefined,
+  };
+}

package/src/pages/doc.astro

@@ -5,6 +5,7 @@ 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 { resolveWikiImage } from '@karaoke-cms/astro';
 
 export async function getStaticPaths() {
   const docs = await getCollection('docs', ({ data }) => data.publish === true);
@@ -36,7 +37,7 @@ const allDocs = (await getCollection('docs', ({ data }) => data.publish === true
   </nav>
   <article class="docs-article">
     {entry.data.featured_image && (
-      <img src={entry.data.featured_image} alt="" class="docs-article-image" />
+      <img src={resolveWikiImage(entry.data.featured_image)} alt="" class="docs-article-image" />
     )}
     <h1 class="docs-article-title">{entry.data.title}</h1>
     {entry.data.tags && entry.data.tags.length > 0 && (