@functional-examples/documentation 0.0.0-alpha.1 → 0.0.0-alpha.2

package/README.md

@@ -0,0 +1,61 @@
+# @functional-examples/documentation
+
+Documentation generation plugin for functional-examples.
+
+## Installation
+
+```bash
+npm install @functional-examples/documentation
+```
+
+## Overview
+
+This plugin generates documentation from your scanned examples using customizable templates. It supports both Markdown and Markdoc output formats, with Eta-powered template rendering.
+
+## Usage
+
+```typescript
+import { createDocumentationPlugin } from '@functional-examples/documentation';
+import type { Config } from 'functional-examples';
+
+const config: Config = {
+  plugins: [
+    createDocumentationPlugin({
+      outputDir: './docs/examples',
+      format: 'markdown',
+    }),
+  ],
+};
+
+export default config;
+```
+
+## Features
+
+- **Template-based generation**: Eta templates for full control over output
+- **Per-example templates**: Override the template for specific examples
+- **Prose file rendering**: README.md files in examples are rendered with helper expansion
+- **Region references**: Use `file()` and `region()` helpers in prose to embed code
+- **Guide hydration**: Expand cross-example references in standalone guide documents
+- **Check mode**: CI-friendly `--check` flag to verify docs are up-to-date
+- **Multiple formats**: Markdown and Markdoc output
+
+## Template Helpers
+
+Inside prose files (README.md in examples), use:
+
+```markdown
+<%= file('utils.ts') %>       <% /* Embed a file as a fenced code block */ %>
+<%= region('setup') %>        <% /* Embed a code region */ %>
+```
+
+Inside guide documents, reference any example:
+
+```markdown
+<%= example('basic-usage').file('scan.ts') %>
+<%= example('basic-usage').region('config-setup') %>
+```
+
+## License
+
+MIT

package/README.md.template

@@ -0,0 +1,61 @@
+# @functional-examples/documentation
+
+Documentation generation plugin for functional-examples.
+
+## Installation
+
+```bash
+npm install @functional-examples/documentation
+```
+
+## Overview
+
+This plugin generates documentation from your scanned examples using customizable templates. It supports both Markdown and Markdoc output formats, with Eta-powered template rendering.
+
+## Usage
+
+```typescript
+import { createDocumentationPlugin } from '@functional-examples/documentation';
+import type { Config } from 'functional-examples';
+
+const config: Config = {
+  plugins: [
+    createDocumentationPlugin({
+      outputDir: './docs/examples',
+      format: 'markdown',
+    }),
+  ],
+};
+
+export default config;
+```
+
+## Features
+
+- **Template-based generation**: Eta templates for full control over output
+- **Per-example templates**: Override the template for specific examples
+- **Prose file rendering**: README.md files in examples are rendered with helper expansion
+- **Region references**: Use `file()` and `region()` helpers in prose to embed code
+- **Guide hydration**: Expand cross-example references in standalone guide documents
+- **Check mode**: CI-friendly `--check` flag to verify docs are up-to-date
+- **Multiple formats**: Markdown and Markdoc output
+
+## Template Helpers
+
+Inside prose files (README.md in examples), use:
+
+```markdown
+<\%= file('utils.ts') \%>       <\% /* Embed a file as a fenced code block */ \%>
+<\%= region('setup') \%>        <\% /* Embed a code region */ \%>
+```
+
+Inside guide documents, reference any example:
+
+```markdown
+<\%= example('basic-usage').file('scan.ts') \%>
+<\%= example('basic-usage').region('config-setup') \%>
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@functional-examples/documentation",
-  "version": "0.0.0-alpha.1",
+  "version": "0.0.0-alpha.2",
   "type": "module",
   "description": "Documentation generation plugin for functional-examples",
   "publishConfig": {
@@ -20,7 +20,7 @@
     "templates"
   ],
   "peerDependencies": {
-    "functional-examples": "0.0.0-alpha.1"
+    "functional-examples": "0.0.0-alpha.2"
   },
   "peerDependenciesMeta": {
     "yaml": {
@@ -31,15 +31,15 @@
     "cli-forge": "1.2.0",
     "eta": "^3.5.0",
     "zod": "4.3.6",
-    "@functional-examples/devkit": "0.0.0-alpha.1"
+    "@functional-examples/devkit": "0.0.0-alpha.2"
   },
   "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"
+    "@functional-examples/devkit": "0.0.0-alpha.2",
+    "functional-examples": "0.0.0-alpha.2"
   },
   "license": "MIT",
   "author": {
@@ -57,6 +57,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.lib.json",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "extract-docs": "typedoc --options typedoc.json"
   }
 }