@karaoke-cms/module-docs 0.15.0 → 0.16.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@karaoke-cms/module-docs",
   "type": "module",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Docs module for karaoke-cms — documentation pages with sidebar navigation",
   "main": "./src/index.ts",
   "exports": {
@@ -23,13 +23,13 @@
   ],
   "peerDependencies": {
     "astro": ">=6.0.0",
-    "@karaoke-cms/contracts": "^0.15.0"
+    "@karaoke-cms/contracts": "^0.16.0"
   },
   "devDependencies": {
     "astro": "^6.0.8",
     "vitest": "^4.1.1",
-    "@karaoke-cms/astro": "0.15.0",
-    "@karaoke-cms/contracts": "0.15.0"
+    "@karaoke-cms/astro": "0.16.0",
+    "@karaoke-cms/contracts": "0.16.0"
   },
   "scripts": {
     "test": "vitest run test/docs-factory.test.js"

package/src/index.ts

@@ -1,7 +1,8 @@
-import type { ModuleInstance } from '@karaoke-cms/contracts';
+import type { DocsSection, ModuleInstance } from '@karaoke-cms/contracts';
 import { cssContract } from './css-contract.js';
 
 export { cssContract } from './css-contract.js';
+export type { DocsSection } from '@karaoke-cms/contracts';
 // docsSchema is exported from '@karaoke-cms/module-docs/schema' to avoid
 // pulling zod into the config-loading context.
 
@@ -24,43 +25,26 @@ export interface DocsConfig {
 }
 
 /**
- * Docs module — documentation pages with sidebar navigation.
- *
- * 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 — default section
- * import { docs } from '@karaoke-cms/module-docs';
- * export default defineConfig({
- *   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' })],
- * });
+ * Shared helper: derive mount, folder, id, and label from config fields.
+ * Used by both docsFromSingle and docsFromSection to keep derivation in sync.
  */
-export function docs(config: DocsConfig = {}): ModuleInstance {
-  const mount = (config.mount ?? '/docs').replace(/\/$/, '');
+function computeDocsMeta(cfg: { mount?: string; folder?: string; id?: string; label?: string }) {
+  const mount = (cfg.mount ?? '/docs').replace(/\/$/, '');
   const rawFolder = mount.replace(/^\//, '');
-  if (config.folder === undefined && rawFolder === '') {
+  if (cfg.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, ' '));
+  const folder = cfg.folder ?? (rawFolder || 'docs');
+  const id = cfg.id ?? (folder.replace(/\//g, '-') || 'docs');
+  const label = cfg.label ?? id.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+  return { mount, folder, id, label };
+}
+
+function docsFromSingle(config: DocsConfig = {}): ModuleInstance {
+  const { mount, folder, id, label } = computeDocsMeta(config);
   return {
     _type: 'module-instance',
     id,
@@ -82,3 +66,68 @@ export function docs(config: DocsConfig = {}): ModuleInstance {
     scaffoldPages: undefined,
   };
 }
+
+function docsFromSection(s: DocsSection): ModuleInstance {
+  const { mount, folder, id, label } = computeDocsMeta(s);
+  return {
+    _type: 'module-instance',
+    id,
+    mount,
+    enabled: true,
+    collection: {
+      name: id,
+      folder,
+      label,
+      layout: s.layout ?? 'default',
+      sidebarStyle: s.sidebarStyle ?? 'tree',
+    },
+    // routes is empty — karaoke() generates per-instance pages via codegen
+    routes: [],
+    menuEntries: [{
+      id,
+      name: label,
+      path: mount,
+      section: 'main',
+      weight: s.weight ?? 20,
+      ...(s.parent !== undefined ? { parent: s.parent } : {}),
+    }],
+    cssContract,
+    hasDefaultCss: false,
+    defaultCssPath: undefined,
+    scaffoldPages: undefined,
+  };
+}
+
+/**
+ * Docs module — documentation pages with sidebar navigation.
+ *
+ * Single-form: returns one ModuleInstance.
+ * Array-form: accepts DocsSection[] and returns ModuleInstance[] (one per active section).
+ * Sections with `enabled: false` are excluded from the returned array.
+ *
+ * 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 — single section
+ * modules: [docs({ mount: '/docs' })]
+ *
+ * @example
+ * // karaoke.config.ts — multiple sections with menu ordering
+ * modules: [
+ *   docs([
+ *     { id: 'docs',     mount: '/docs',     label: 'Docs',          weight: 20 },
+ *     { id: 'api-docs', mount: '/api-docs', folder: 'api-reference', label: 'API Reference', weight: 25, parent: 'docs' },
+ *   ]),
+ * ]
+ */
+export function docs(config: DocsSection[]): ModuleInstance[];
+export function docs(config?: DocsConfig): ModuleInstance;
+export function docs(config?: DocsConfig | DocsSection[]): ModuleInstance | ModuleInstance[] {
+  if (Array.isArray(config)) {
+    return config.filter(s => s.enabled !== false).map(s => docsFromSection(s));
+  }
+  return docsFromSingle(config);
+}

package/src/pages/doc.astro

@@ -1,9 +1,18 @@
 ---
-// TODO: use mount path from virtual module once mount-aware routing is implemented.
-// For now, mount is assumed to be /docs.
+// NOTE: this is a reference implementation only — it is NOT used as an injected route.
+// The actual route entrypoint is generated by karaoke() into
+//   .astro/generated/karaoke-cms/{id}/doc.astro
+// Keep this file in sync with generateDocPage() in:
+//   packages/astro/src/codegen/generate-docs-instance.ts
+//
+// Differences from the generated version:
+//   - mount is hardcoded to /docs (default instance only)
+//   - collection is hardcoded to 'docs'
+//   - multi-section switcher (docsSections) is omitted
 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 DocsTree from '@karaoke-cms/astro/components/DocsTree.astro';
 import { resolveWikiImage } from '@karaoke-cms/astro';
 
 export async function getStaticPaths() {
@@ -17,23 +26,28 @@ export async function getStaticPaths() {
 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));
+
+// Show the right sidebar only when the current entry is a directory (has child entries).
+const isDirectory = allDocs.some(d => d.id.startsWith(entry.id + '/'));
 ---
 
 <DefaultPage title={entry.data.title} 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>
+    <details class="docs-sidebar-wrap" open>
+      <summary class="docs-sidebar-toggle">Docs</summary>
+      <DocsTree entries={allDocs} currentId={entry.id} mount="/docs" />
+    </details>
   </nav>
+  {isDirectory && (
+    <aside class="docs-page-nav" slot="right">
+      <details class="docs-sidebar-wrap" open>
+        <summary class="docs-sidebar-toggle">In this section</summary>
+        <DocsTree entries={allDocs} currentId={entry.id} mount="/docs" rootPath={entry.id} maxDepth={1} />
+      </details>
+    </aside>
+  )}
   <article class="docs-article">
     {entry.data.featured_image && (
       <img src={resolveWikiImage(entry.data.featured_image)} alt="" class="docs-article-image" />