@functional-examples/documentation 0.0.0-alpha.1

package/dist/templates/guide-renderer.js

@@ -0,0 +1,93 @@
+/**
+ * Guide hydration renderer — expands example references in standalone
+ * markdown guides that reference files/regions from *any* scanned example.
+ *
+ * Unlike prose helpers (scoped to a single example), the guide renderer
+ * creates a cross-example lookup so authors can write:
+ *
+ * ```markdown
+ * <%= example('basic-usage').file('scan.ts') %>
+ * <%= example('basic-usage').region('config-setup') %>
+ * ```
+ */
+import { Eta } from 'eta';
+import * as fs from 'node:fs/promises';
+import { templateHelpers } from './helpers.js';
+import { fencedBlock } from './prose-helpers.js';
+/**
+ * Create a guide renderer bound to a set of scanned examples.
+ *
+ * Guide templates can reference any example by ID:
+ * ```markdown
+ * <%= example('basic-usage').file('scan.ts') %>
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createGuideRenderer } from '@functional-examples/documentation';
+ * import { scan } from 'functional-examples';
+ *
+ * const { examples } = await scan({ root: workspaceRoot });
+ * const renderer = createGuideRenderer(examples);
+ * const html = await renderer.renderFile('docs/guides/getting-started.md');
+ * ```
+ */
+export function createGuideRenderer(examples) {
+    // Build lookup map: example ID → ScannedExample
+    const examplesById = new Map(examples.map((ex) => [ex.id, ex]));
+    /**
+     * Create a scoped accessor for a single example.
+     */
+    function exampleAccessor(id) {
+        const ex = examplesById.get(id);
+        if (!ex) {
+            const available = [...examplesById.keys()].join(', ');
+            throw new Error(`Guide helper example(): no example found with id "${id}". Available: ${available}`);
+        }
+        return {
+            file(relativePath) {
+                const found = ex.files.find((f) => f.relativePath === relativePath);
+                if (!found) {
+                    const fileList = ex.files.map((f) => f.relativePath).join(', ');
+                    throw new Error(`Guide helper example('${id}').file(): no file "${relativePath}". Available: ${fileList}`);
+                }
+                const lang = templateHelpers.langFromPath(relativePath);
+                const content = found.parsed ?? found.raw ?? '';
+                return fencedBlock(lang, content);
+            },
+            region(regionId) {
+                const match = templateHelpers.region(ex.files, regionId);
+                if (!match) {
+                    throw new Error(`Guide helper example('${id}').region(): no region "${regionId}" found`);
+                }
+                const lang = templateHelpers.langFromPath(match.file.relativePath);
+                return fencedBlock(lang, match.content);
+            },
+            files: ex.files,
+            metadata: ex.metadata,
+            title: ex.title,
+            description: ex.description,
+        };
+    }
+    // Separate Eta instance for guide templates with injected helper names
+    const guideEta = new Eta({
+        autoEscape: false,
+        autoTrim: false,
+        functionHeader: 'var example = it.example, examples = it.examples, helpers = it.helpers;',
+    });
+    function render(markdown) {
+        return guideEta
+            .renderString(markdown, {
+            example: exampleAccessor,
+            examples,
+            helpers: templateHelpers,
+        })
+            .replaceAll('\\%', '%');
+    }
+    async function renderFile(filePath) {
+        const content = await fs.readFile(filePath, 'utf-8');
+        return render(content);
+    }
+    return { render, renderFile };
+}
+//# sourceMappingURL=guide-renderer.js.map

package/dist/templates/guide-renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide-renderer.js","sourceRoot":"","sources":["../../src/templates/guide-renderer.ts"],"names":[],"mappings":"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"}

package/dist/templates/helpers.d.ts

@@ -0,0 +1,45 @@
+import type { ExampleFile } from '@functional-examples/devkit';
+/**
+ * Infer a code fence language identifier from a file path's extension.
+ */
+export declare function langFromPath(filePath: string): string;
+/**
+ * Select a specific hunk (region) by ID across all files.
+ * Returns the first matching hunk or undefined.
+ */
+export declare function region(files: ExampleFile[], regionId: string): {
+    file: ExampleFile;
+    content: string;
+} | undefined;
+/**
+ * Filter files by extension.
+ */
+export declare function filesByExt(files: ExampleFile[], ext: string): ExampleFile[];
+/**
+ * Check whether a file is a prose/documentation file (e.g. README.md).
+ */
+export declare function isProseFile(file: ExampleFile): boolean;
+/**
+ * Look up a hunk description from the docs metadata.
+ * Returns the description string or undefined.
+ */
+export declare function hunkDescription(metadata: Record<string, unknown>, hunkId: string): string | undefined;
+/**
+ * Convert a string to a URL-friendly slug.
+ * Strips backticks, lowercases, replaces non-alphanumeric runs with dashes,
+ * and trims leading/trailing dashes.
+ */
+export declare function slugify(text: string): string;
+/**
+ * Collected template helpers exposed as `it.helpers`.
+ */
+export declare const templateHelpers: {
+    readonly langFromPath: typeof langFromPath;
+    readonly region: typeof region;
+    readonly filesByExt: typeof filesByExt;
+    readonly isProseFile: typeof isProseFile;
+    readonly hunkDescription: typeof hunkDescription;
+    readonly slugify: typeof slugify;
+};
+export type TemplateHelpers = typeof templateHelpers;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/templates/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/templates/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAgC/D;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKrD;AAED;;;GAGG;AACH,wBAAgB,MAAM,CACpB,KAAK,EAAE,WAAW,EAAE,EACpB,QAAQ,EAAE,MAAM,GACf;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CASpD;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,WAAW,EAAE,EACpB,GAAG,EAAE,MAAM,GACV,WAAW,EAAE,CAGf;AAKD;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAItD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,MAAM,EAAE,MAAM,GACb,MAAM,GAAG,SAAS,CAKpB;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM5C;AAED;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;;CAOlB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC"}

package/dist/templates/helpers.js

@@ -0,0 +1,104 @@
+/** Map of file extensions to language identifiers for code fences. */
+const EXT_TO_LANG = {
+    '.ts': 'typescript',
+    '.tsx': 'tsx',
+    '.js': 'javascript',
+    '.jsx': 'jsx',
+    '.mjs': 'javascript',
+    '.cjs': 'javascript',
+    '.mts': 'typescript',
+    '.cts': 'typescript',
+    '.json': 'json',
+    '.yaml': 'yaml',
+    '.yml': 'yaml',
+    '.md': 'markdown',
+    '.css': 'css',
+    '.scss': 'scss',
+    '.html': 'html',
+    '.sh': 'bash',
+    '.bash': 'bash',
+    '.py': 'python',
+    '.rs': 'rust',
+    '.go': 'go',
+    '.toml': 'toml',
+    '.xml': 'xml',
+    '.sql': 'sql',
+    '.graphql': 'graphql',
+    '.vue': 'vue',
+    '.svelte': 'svelte',
+};
+/**
+ * Infer a code fence language identifier from a file path's extension.
+ */
+export function langFromPath(filePath) {
+    const dotIdx = filePath.lastIndexOf('.');
+    if (dotIdx === -1)
+        return '';
+    const ext = filePath.slice(dotIdx).toLowerCase();
+    return EXT_TO_LANG[ext] ?? ext.slice(1);
+}
+/**
+ * Select a specific hunk (region) by ID across all files.
+ * Returns the first matching hunk or undefined.
+ */
+export function region(files, regionId) {
+    for (const file of files) {
+        if (!file.hunks)
+            continue;
+        const hunk = file.hunks.find((h) => h.id === regionId);
+        if (hunk) {
+            return { file, content: hunk.content };
+        }
+    }
+    return undefined;
+}
+/**
+ * Filter files by extension.
+ */
+export function filesByExt(files, ext) {
+    const normalized = ext.startsWith('.') ? ext : `.${ext}`;
+    return files.filter((f) => f.relativePath.endsWith(normalized));
+}
+/** Extensions considered prose/documentation rather than code. */
+const PROSE_EXTENSIONS = new Set(['.md', '.mdx', '.mdoc', '.txt', '.rst']);
+/**
+ * Check whether a file is a prose/documentation file (e.g. README.md).
+ */
+export function isProseFile(file) {
+    const dotIdx = file.relativePath.lastIndexOf('.');
+    if (dotIdx === -1)
+        return false;
+    return PROSE_EXTENSIONS.has(file.relativePath.slice(dotIdx).toLowerCase());
+}
+/**
+ * Look up a hunk description from the docs metadata.
+ * Returns the description string or undefined.
+ */
+export function hunkDescription(metadata, hunkId) {
+    const docs = metadata.docs;
+    return docs?.hunks?.[hunkId];
+}
+/**
+ * Convert a string to a URL-friendly slug.
+ * Strips backticks, lowercases, replaces non-alphanumeric runs with dashes,
+ * and trims leading/trailing dashes.
+ */
+export function slugify(text) {
+    return text
+        .replace(/`/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+/**
+ * Collected template helpers exposed as `it.helpers`.
+ */
+export const templateHelpers = {
+    langFromPath,
+    region,
+    filesByExt,
+    isProseFile,
+    hunkDescription,
+    slugify,
+};
+//# sourceMappingURL=helpers.js.map

package/dist/templates/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/templates/helpers.ts"],"names":[],"mappings":"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"}

package/dist/templates/prose-helpers.d.ts

@@ -0,0 +1,26 @@
+import type { ExampleFile } from '@functional-examples/devkit';
+import { ConsumptionTracker } from './consumption-tracker.js';
+import { templateHelpers } from './helpers.js';
+/** Helpers injected into prose Eta templates as top-level variables. */
+export interface ProseHelpers {
+    /** Render a file as a fenced code block and mark it consumed. */
+    file: (relativePath: string) => string;
+    /** Render a region/hunk as a fenced code block and mark its file consumed. */
+    region: (regionId: string) => string;
+    /** All example files (read-only). */
+    files: ExampleFile[];
+    /** Standard template helpers (langFromPath, slugify, etc.). */
+    helpers: typeof templateHelpers;
+}
+/**
+ * Build a fenced code block string for a given language and content.
+ */
+export declare function fencedBlock(lang: string, content: string): string;
+/**
+ * Create prose-template helpers bound to a specific set of files and tracker.
+ *
+ * These helpers are injected into Eta prose templates via `functionHeader`
+ * so authors can write `<%= file('utils.ts') %>` instead of `<%= it.file('utils.ts') %>`.
+ */
+export declare function createProseHelpers(files: ExampleFile[], tracker: ConsumptionTracker): ProseHelpers;
+//# sourceMappingURL=prose-helpers.d.ts.map

package/dist/templates/prose-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prose-helpers.d.ts","sourceRoot":"","sources":["../../src/templates/prose-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,iEAAiE;IACjE,IAAI,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC;IACvC,8EAA8E;IAC9E,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IACrC,qCAAqC;IACrC,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,+DAA+D;IAC/D,OAAO,EAAE,OAAO,eAAe,CAAC;CACjC;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,EAAE,EACpB,OAAO,EAAE,kBAAkB,GAC1B,YAAY,CA8Bd"}

package/dist/templates/prose-helpers.js

@@ -0,0 +1,39 @@
+import { templateHelpers } from './helpers.js';
+/**
+ * Build a fenced code block string for a given language and content.
+ */
+export function fencedBlock(lang, content) {
+    return `\`\`\`${lang}\n${content}\n\`\`\``;
+}
+/**
+ * Create prose-template helpers bound to a specific set of files and tracker.
+ *
+ * These helpers are injected into Eta prose templates via `functionHeader`
+ * so authors can write `<%= file('utils.ts') %>` instead of `<%= it.file('utils.ts') %>`.
+ */
+export function createProseHelpers(files, tracker) {
+    return {
+        file(relativePath) {
+            const found = files.find((f) => f.relativePath === relativePath);
+            if (!found) {
+                throw new Error(`Prose helper file(): no file found with relativePath "${relativePath}"`);
+            }
+            tracker.consume(relativePath);
+            const lang = templateHelpers.langFromPath(relativePath);
+            const content = found.parsed ?? found.raw ?? '';
+            return fencedBlock(lang, content);
+        },
+        region(regionId) {
+            const match = templateHelpers.region(files, regionId);
+            if (!match) {
+                throw new Error(`Prose helper region(): no region found with id "${regionId}"`);
+            }
+            tracker.consume(match.file.relativePath);
+            const lang = templateHelpers.langFromPath(match.file.relativePath);
+            return fencedBlock(lang, match.content);
+        },
+        files,
+        helpers: templateHelpers,
+    };
+}
+//# sourceMappingURL=prose-helpers.js.map

package/dist/templates/prose-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prose-helpers.js","sourceRoot":"","sources":["../../src/templates/prose-helpers.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAc/C;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,OAAe;IACvD,OAAO,SAAS,IAAI,KAAK,OAAO,UAAU,CAAC;AAC7C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAoB,EACpB,OAA2B;IAE3B,OAAO;QACL,IAAI,CAAC,YAAoB;YACvB,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,YAAY,CAAC,CAAC;YACjE,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,MAAM,IAAI,KAAK,CACb,yDAAyD,YAAY,GAAG,CACzE,CAAC;YACJ,CAAC;YACD,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;YAC9B,MAAM,IAAI,GAAG,eAAe,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC;YACxD,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,EAAE,CAAC;YAChD,OAAO,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACpC,CAAC;QAED,MAAM,CAAC,QAAgB;YACrB,MAAM,KAAK,GAAG,eAAe,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;YACtD,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,MAAM,IAAI,KAAK,CACb,mDAAmD,QAAQ,GAAG,CAC/D,CAAC;YACJ,CAAC;YACD,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACzC,MAAM,IAAI,GAAG,eAAe,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACnE,OAAO,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAC1C,CAAC;QAED,KAAK;QACL,OAAO,EAAE,eAAe;KACzB,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Options for the documentation plugin factory.
+ */
+export interface DocumentationPluginOptions {
+    /** Output directory for generated docs (default: './docs') */
+    outputDir?: string;
+    /** Output format: 'markdown' or 'mdoc' (default: 'markdown') */
+    format?: 'markdown' | 'mdoc';
+    /** Path to custom Eta template file */
+    template?: string;
+    /** Enable the markdown frontmatter extractor (default: false) */
+    enableExtractor?: boolean;
+}
+/**
+ * Resolved options with defaults applied.
+ */
+export interface ResolvedDocumentationPluginOptions {
+    outputDir: string;
+    format: 'markdown' | 'mdoc';
+    template?: string;
+    enableExtractor: boolean;
+}
+/**
+ * Documentation-specific metadata that examples can declare.
+ */
+export interface DocsMetadata {
+    docs?: {
+        /** Per-example template override (path to .eta file) */
+        template?: string;
+        /** Skip this example during doc generation */
+        skip?: boolean;
+        /** Custom output filename (without extension) */
+        outputName?: string;
+    };
+}
+/**
+ * Default option values.
+ */
+export declare const DEFAULTS: {
+    outputDir: string;
+    format: "markdown";
+    enableExtractor: false;
+};
+/**
+ * Resolve user options with defaults.
+ */
+export declare function resolveOptions(options?: DocumentationPluginOptions): ResolvedDocumentationPluginOptions;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IAC7B,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,kCAAkC;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE;QACL,wDAAwD;QACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,8CAA8C;QAC9C,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,iDAAiD;QACjD,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED;;GAEG;AACH,eAAO,MAAM,QAAQ;;;;CAMpB,CAAC;AAEF;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,GAAE,0BAA+B,GACvC,kCAAkC,CAOpC"}

package/dist/types.js

@@ -0,0 +1,20 @@
+/**
+ * Default option values.
+ */
+export const DEFAULTS = {
+    outputDir: './docs',
+    format: 'markdown',
+    enableExtractor: false,
+};
+/**
+ * Resolve user options with defaults.
+ */
+export function resolveOptions(options = {}) {
+    return {
+        outputDir: options.outputDir ?? DEFAULTS.outputDir,
+        format: options.format ?? DEFAULTS.format,
+        template: options.template,
+        enableExtractor: options.enableExtractor ?? DEFAULTS.enableExtractor,
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAsCA;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,SAAS,EAAE,QAAQ;IACnB,MAAM,EAAE,UAAmB;IAC3B,eAAe,EAAE,KAAK;CAGvB,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,cAAc,CAC5B,UAAsC,EAAE;IAExC,OAAO;QACL,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,QAAQ,CAAC,SAAS;QAClD,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,QAAQ,CAAC,MAAM;QACzC,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,QAAQ,CAAC,eAAe;KACrE,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@functional-examples/documentation",
+  "version": "0.0.0-alpha.1",
+  "type": "module",
+  "description": "Documentation generation plugin for functional-examples",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "peerDependencies": {
+    "functional-examples": "0.0.0-alpha.1"
+  },
+  "peerDependenciesMeta": {
+    "yaml": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "cli-forge": "1.2.0",
+    "eta": "^3.5.0",
+    "zod": "4.3.6",
+    "@functional-examples/devkit": "0.0.0-alpha.1"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.8",
+    "typescript": "^5.7.2",
+    "vitest": "^1.3.1",
+    "yaml": "^2.7.1",
+    "@functional-examples/devkit": "0.0.0-alpha.1",
+    "functional-examples": "0.0.0-alpha.1"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Craigory Coppola",
+    "url": "https://craigory.dev"
+  },
+  "homepage": "https://craigory.dev/functional-examples",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AgentEnder/functional-examples.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AgentEnder/functional-examples/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.lib.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/templates/@slug.md.template

@@ -0,0 +1,40 @@
+---
+generated: true
+---
+
+# <%= it.title %>
+
+<% if (it.description) { -%>
+<%= it.description %>
+
+<% } -%>
+<% /* ── Rendered prose (README, docs, etc. with file/region helpers expanded) ── */ -%>
+<% it.renderedProse.forEach(function(content) { -%>
+<%= content %>
+
+<% }); -%>
+<% /* ── Unconsumed code files ── */ -%>
+<% it.unconsumedFiles.forEach(function(file) { -%>
+## `<%= file.relativePath %>`
+
+<% if (file.hunks && file.hunks.length > 0) { -%>
+<% file.hunks.forEach(function(hunk) { -%>
+### Region: `<%= hunk.id %>`
+
+<% var desc = it.helpers.hunkDescription(it.metadata, hunk.id); -%>
+<% if (desc) { -%>
+<%= desc %>
+
+<% } -%>
+```<%= it.helpers.langFromPath(file.relativePath) %>
+<%= hunk.content %>
+```
+
+<% }); -%>
+<% } else { -%>
+```<%= it.helpers.langFromPath(file.relativePath) %>
+<%= file.parsed || file.raw || '' %>
+```
+
+<% } -%>
+<% }); -%>

package/templates/@slug.mdoc.template

@@ -0,0 +1,40 @@
+---
+generated: true
+---
+
+# <%= it.title %> {% #<%= it.helpers.slugify(it.title) %> %}
+
+<% if (it.description) { -%>
+<%= it.description %>
+
+<% } -%>
+<% /* ── Rendered prose (README, docs, etc. with file/region helpers expanded) ── */ -%>
+<% it.renderedProse.forEach(function(content) { -%>
+<%= content %>
+
+<% }); -%>
+<% /* ── Unconsumed code files ── */ -%>
+<% it.unconsumedFiles.forEach(function(file) { -%>
+## `<%= file.relativePath %>` {% #<%= it.helpers.slugify(file.relativePath) %> %}
+
+<% if (file.hunks && file.hunks.length > 0) { -%>
+<% file.hunks.forEach(function(hunk) { -%>
+### Region: `<%= hunk.id %>` {% #region-<%= it.helpers.slugify(hunk.id) %> %}
+
+<% var desc = it.helpers.hunkDescription(it.metadata, hunk.id); -%>
+<% if (desc) { -%>
+<%= desc %>
+
+<% } -%>
+```<%= it.helpers.langFromPath(file.relativePath) %> {% process=true %}
+<%= hunk.content %>
+```
+
+<% }); -%>
+<% } else { -%>
+```<%= it.helpers.langFromPath(file.relativePath) %> {% process=true %}
+<%= file.parsed || file.raw || '' %>
+```
+
+<% } -%>
+<% }); -%>

package/templates/index.md.template

@@ -0,0 +1,9 @@
+---
+generated: true
+---
+
+# Examples
+
+<% it.examples.forEach(function(example) { -%>
+- [<%= example.title %>](./<%= example.id %>.md)<% if (example.description) { %> — <%= example.description %><% } %>
+<% }); -%>

package/templates/index.mdoc.template

@@ -0,0 +1,9 @@
+---
+generated: true
+---
+
+# Examples {% #examples %}
+
+<% it.examples.forEach(function(example) { -%>
+- [<%= example.title %>](./<%= example.id %>.mdoc)<% if (example.description) { %> — <%= example.description %><% } %>
+<% }); -%>