API/documentation

@functional-examples/documentation

Documentation generation plugin for functional-examples

npm install @functional-examples/documentation

@functional-examples/documentation

Documentation generation plugin for functional-examples.

Installation

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

import { createDocumentationPlugin } from '@functional-examples/documentation';
import { createJavaScriptPlugin } from '@functional-examples/javascript';
import type { Config } from 'functional-examples';

/**
 * Configuration demonstrating the documentation plugin.
 *
 * The documentation plugin:
 * - Adds the `generate` CLI command
 * - Enables template-based doc generation
 * - Provides prose helpers (file(), region(), fencedBlock())
 */
const config: Config = {
  plugins: [
    createJavaScriptPlugin(),
    createDocumentationPlugin({
      outputDir: 'generated-docs',
      format: 'markdown',
    }),
  ],
  scan: {
    include: ['src/**/*'],
    exclude: ['**/node_modules/**', '**/dist/**'],
  },
};

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:

<%= file('utils.ts') %>       <% /* Embed a file as a fenced code block */ %>
<%= region('setup') %>        <% /* Embed a code region */ %>

Inside guide documents, reference any example:

<%= example('basic-usage').file('scan.ts') %>
<%= example('basic-usage').region('scan') %>

License

MIT

API EXPORTS

Functions

buildTemplateDatafunction

Build the template data model from an Example.

createDocumentationPluginfunction

Create the documentation plugin.

createFileAccessorfunction

Create a FileAccessor for a specific file.

createGuideRendererfunction

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') %> ```

createMarkdownExtractorfunction

Create a markdown frontmatter extractor. Scans for .md files with YAML frontmatter containing at least `id` and `title`. Treats each matching file as a single-file example.

createProseHelpersfunction

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') %>`.

getBuiltinTemplatesDirfunction

Resolve the built-in templates directory relative to this file. At runtime, this file lives at `dist/templates/engine.js`. The templates directory is at `packages/documentation/templates/` — two levels up from `dist/templates/`.

loadTemplatesfunction

Load all `.template` files from a directory (recursively) and parse their paths. Supports nested directory structures like: ``` templates/ index.md.template examples/@example/index.md.template ```

parseTemplateNamefunction

Parse a template's relative path into its descriptor fields. The `@var` convention can appear in any path segment — either in the filename itself or in a directory name: - `@slug.md.template` → variable `slug` (flat, filename) - `examples/@example/index.md.template` → variable `example` (nested, directory)

renderIndexTemplatefunction

Render an aggregate template with all examples.

renderItemTemplatefunction

Render a per-item template for a single example.

renderProseFilesfunction

Render prose files through Eta, expanding `file()` and `region()` helpers, and return which files remain unconsumed.

renderTemplatefunction

Render an example using the default or a custom template file.

substituteVarsfunction

Replace `@var` placeholders in a pattern with values from a vars map. Example: `substituteVars('@slug.md', { slug: 'getting-started' })` → `getting-started.md`

Classes

ConsumptionTrackerclass

Tracks which example files have been "consumed" by prose template helpers (e.g. `file()` or `region()`). Consumed files are excluded from the "remaining files" section in the rendered output.

Interfaces

DocsMetadatainterface

Documentation-specific metadata that examples can declare.

ExampleAccessorinterface

Scoped API returned by `example(id)` inside guide templates.

FileAccessorinterface

Chainable accessor returned by `file()` in both prose and guide contexts. Supports two usage patterns: - `<%= file('path.ts') %>` — renders the whole file (calls `toString()`) - `<%= file('path.ts').region('id') %>` — renders a scoped region

GuideRendererinterface

A renderer that expands example references in guide markdown.

GuideRendererOptionsinterface

Options for createGuideRenderer.

IndexTemplateDatainterface

Data model for aggregate (index) templates.

ProseHelpersinterface

Helpers injected into prose Eta templates as top-level variables.

ProseRenderResultinterface

Result of rendering prose files through Eta.

RenderedFileinterface

Rendered output ready to write.