functional-examplesFUNCTIONAL-EXAMPLES
EXAMPLES/documentation-plugin

Documentation Plugin

Demonstrates using the documentation plugin to generate markdown documentation from scanned examples. Shows template rendering, region extraction, and generated output structure.

meta-yml8 FILESdocstemplatesgeneration

Documentation Plugin

Demonstrates using @functional-examples/documentation to generate markdown from scanned examples.

What This Shows

  • Configuring the documentation plugin alongside the JavaScript plugin
  • Running the documentation command to generate markdown files
  • Generated output structure: per-example pages with regions + an index page
  • Snapshot testing to verify generated output doesn't drift

Running

bash
1# Scan for examples
2bash demo.sh
3
4# Generate documentation from scanned examples
5bash generate.sh

Generated Output

The documentation command produces:

  • generated-docs/doc-sample.md — per-example page with title, description, and code regions
  • generated-docs/index.md — index linking to all generated example pages

The snapshot in __snapshots__/doc-sample.md shows the expected output structure.

Configuration

The functional-examples.config.ts registers both the JavaScript plugin (for extraction) and the documentation plugin (for generation). The documentation plugin adds the documentation CLI command with outputDir and format options.

generated: true

Sample for Documentation

A simple example demonstrating documentation generation

src/sample.ts

Region: setup

typescript
1import { readFileSync } from 'node:fs';
2
3/**
4 * Read and parse a configuration file.
5 */
6export function loadConfig(path: string): Record<string, unknown> {
7  const content = readFileSync(path, 'utf-8');
8  return JSON.parse(content);
9}

Region: usage

typescript
1// Load configuration from a JSON file
2const config = loadConfig('config.json');
3console.log('Loaded config:', config);

All Example Files

FILE EXPLORER
README.md
1# Documentation Plugin
2
3Demonstrates using `@functional-examples/documentation` to generate markdown from scanned examples.
4
5## What This Shows
6
7- Configuring the documentation plugin alongside the JavaScript plugin
8- Running the `documentation` command to generate markdown files
9- Generated output structure: per-example pages with regions + an index page
10- Snapshot testing to verify generated output doesn't drift
11
12## Running
13
14```bash
15# Scan for examples
16bash demo.sh
17
18# Generate documentation from scanned examples
19bash generate.sh
20```
21
22## Generated Output
23
24The `documentation` command produces:
25- **`generated-docs/doc-sample.md`** — per-example page with title, description, and code regions
26- **`generated-docs/index.md`** — index linking to all generated example pages
27
28The snapshot in `__snapshots__/doc-sample.md` shows the expected output structure.
29
30## Configuration
31
32The `functional-examples.config.ts` registers both the JavaScript plugin (for extraction) and the documentation plugin (for generation). The documentation plugin adds the `documentation` CLI command with `outputDir` and `format` options.
33