@karaoke-cms/module-docs 0.9.5

package/README.md

@@ -0,0 +1,69 @@
+# @karaoke-cms/module-docs
+
+Docs module for karaoke-cms — documentation pages with a left-sidebar navigation showing all published docs in alphabetical order.
+
+## Installation
+
+```bash
+npm install @karaoke-cms/module-docs
+```
+
+## 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 { docs } from '@karaoke-cms/module-docs';
+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' }), docs({ mount: '/docs' })],
+  }),
+});
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `mount` | `string` | `'/docs'` | URL prefix for all docs routes |
+| `enabled` | `boolean` | `true` | Set `false` to disable the module entirely |
+
+## Routes
+
+All routes are relative to `mount`:
+
+| Pattern | Description |
+|---------|-------------|
+| `{mount}` | Docs home — lists all published doc titles |
+| `{mount}/list` | Standalone full-list view |
+| `{mount}/[slug]` | Individual doc page with left-sidebar navigation |
+
+## Frontmatter
+
+```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)
+---
+```
+
+## What's new in 0.9.5
+
+- **`featured_image` support** added to the docs schema
+- **`enabled` flag** — `docs({ mount: '/docs', enabled: false })` disables the module without removing it from config
+- Fixed workspace symlink registration — `@karaoke-cms/module-docs` is now correctly wired in the website app

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@karaoke-cms/module-docs",
+  "type": "module",
+  "version": "0.9.5",
+  "description": "Docs module for karaoke-cms — documentation pages with sidebar navigation",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./schema": "./src/schema.ts",
+    "./pages/home": "./src/pages/home.astro",
+    "./pages/list": "./src/pages/list.astro",
+    "./pages/doc": "./src/pages/doc.astro"
+  },
+  "files": [
+    "src/"
+  ],
+  "keywords": [
+    "astro",
+    "cms",
+    "docs",
+    "documentation",
+    "karaoke-cms"
+  ],
+  "peerDependencies": {
+    "astro": ">=6.0.0",
+    "@karaoke-cms/astro": "^0.9.5"
+  },
+  "devDependencies": {
+    "@karaoke-cms/astro": "workspace:*",
+    "astro": "^6.0.8"
+  },
+  "scripts": {
+    "test": "echo \"Stub — no tests\""
+  }
+}

package/src/css-contract.ts

@@ -0,0 +1,20 @@
+/**
+ * CSS class names the docs module promises to use in its markup.
+ * Themes implement these classes to style the docs section.
+ */
+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;

package/src/index.ts

@@ -0,0 +1,40 @@
+import { defineModule } from '@karaoke-cms/astro';
+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.
+
+/**
+ * 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
+ *
+ * @example
+ * // karaoke.config.ts
+ * import { docs } from '@karaoke-cms/module-docs';
+ * export default defineConfig({
+ *   modules: [docs({ mount: '/docs' })],
+ *   theme: themeDefault({ implements: [docs({ mount: '/docs' })] }),
+ * });
+ */
+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 },
+  ],
+});

package/src/pages/doc.astro

@@ -0,0 +1,54 @@
+---
+// TODO: use mount path from virtual module once mount-aware routing is implemented.
+// For now, mount is assumed to be /docs.
+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 docs = await getCollection('docs', ({ data }) => data.publish === true);
+  return docs.map(entry => ({
+    params: { slug: entry.id },
+    props: { entry },
+  }));
+}
+
+const { entry } = Astro.props;
+const { Content } = await render(entry);
+
+// All docs for the sidebar, sorted alphabetically by title
+const allDocs = (await getCollection('docs', ({ data }) => data.publish === true))
+  .sort((a, b) => a.data.title.localeCompare(b.data.title));
+---
+
+<DefaultPage title={`${entry.data.title} — ${siteTitle}`} description={entry.data.description} type="article">
+  <nav class="docs-sidebar" slot="left">
+    <ul class="docs-sidebar-list">
+      {allDocs.map(doc => (
+        <li class="docs-sidebar-item">
+          <a href={`/docs/${doc.id}`} aria-current={doc.id === entry.id ? 'page' : undefined}>
+            {doc.data.title}
+          </a>
+        </li>
+      ))}
+    </ul>
+  </nav>
+  <article class="docs-article">
+    {entry.data.featured_image && (
+      <img src={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 && (
+      <div class="docs-tag-list docs-article-meta">
+        {entry.data.tags.map(tag => (
+          <a href={`/tags/${tag}`} class="docs-tag">#{tag}</a>
+        ))}
+      </div>
+    )}
+    <div class="prose">
+      <Content />
+    </div>
+  </article>
+  <ModuleLoader comments={entry.data.comments} />
+</DefaultPage>

package/src/pages/home.astro

@@ -0,0 +1,30 @@
+---
+// TODO: use mount path from virtual module once mount-aware routing is implemented.
+// For now, mount is assumed to be /docs.
+import { getCollection } from 'astro:content';
+import DefaultPage from '@karaoke-cms/astro/layouts/DefaultPage.astro';
+import { siteTitle } from 'virtual:karaoke-cms/config';
+
+const docs = (await getCollection('docs', ({ data }) => data.publish === true))
+  .sort((a, b) => a.data.title.localeCompare(b.data.title));
+---
+
+<DefaultPage title={`Docs — ${siteTitle}`}>
+  <div class="docs-home">
+    <h1>Docs</h1>
+    {docs.length > 0 ? (
+      <ul class="docs-home-list">
+        {docs.map(doc => (
+          <li class="docs-home-item">
+            <a href={`/docs/${doc.id}`}>{doc.data.title}</a>
+          </li>
+        ))}
+      </ul>
+    ) : (
+      <div class="empty-state">
+        <p>No docs published yet.</p>
+        <p>Create a Markdown file in your vault's <code>docs/</code> folder and set <code>publish: true</code> in the frontmatter to make it appear here.</p>
+      </div>
+    )}
+  </div>
+</DefaultPage>

package/src/pages/list.astro

@@ -0,0 +1,30 @@
+---
+// TODO: use mount path from virtual module once mount-aware routing is implemented.
+// For now, mount is assumed to be /docs.
+import { getCollection } from 'astro:content';
+import DefaultPage from '@karaoke-cms/astro/layouts/DefaultPage.astro';
+import { siteTitle } from 'virtual:karaoke-cms/config';
+
+const docs = (await getCollection('docs', ({ data }) => data.publish === true))
+  .sort((a, b) => a.data.title.localeCompare(b.data.title));
+---
+
+<DefaultPage title={`All Docs — ${siteTitle}`}>
+  <div class="docs-list">
+    <h1>All Docs</h1>
+    {docs.length > 0 ? (
+      <ul>
+        {docs.map(doc => (
+          <li class="docs-list-item">
+            <a href={`/docs/${doc.id}`}>{doc.data.title}</a>
+          </li>
+        ))}
+      </ul>
+    ) : (
+      <div class="empty-state">
+        <p>No docs published yet.</p>
+        <p>Create a Markdown file in your vault's <code>docs/</code> folder and set <code>publish: true</code> in the frontmatter to make it appear here.</p>
+      </div>
+    )}
+  </div>
+</DefaultPage>

package/src/schema.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+
+/**
+ * Frontmatter schema for docs pages.
+ * All fields except `title` are optional — docs validate before and after AI enrichment.
+ */
+export const docsSchema = 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(),
+  featured_image: 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-doc comments override
+  comments:       z.boolean().optional().default(false),
+});