@karaoke-cms/module-docs 0.15.1 → 0.16.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@karaoke-cms/module-docs",
   "type": "module",
-  "version": "0.15.1",
+  "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.1"
+    "@karaoke-cms/contracts": "^0.16.0"
   },
   "devDependencies": {
     "astro": "^6.0.8",
     "vitest": "^4.1.1",
-    "@karaoke-cms/astro": "0.15.1",
-    "@karaoke-cms/contracts": "0.15.1"
+    "@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);
+}