nanodoc

Generate a single self-contained HTML document from source-code comments.

Requirements

• Node.js 20+
• Python on PATH (python or python3)

Install

npm install
npm run build

Usage

nanodoc <entrypoint>

Or with a config file:

nanodoc --config ./nanodoc.json

or during development:

npm run dev -- <entrypoint>

This writes <entrypoint-name>.html to the current working directory.

When using --config, each generated HTML file is written into the config's outputDir (created automatically if missing).

Config File

Use a JSON file with this shape:

{
  "entrypoints": ["./src/main.ts", "./src/guide.py"],
  "outputDir": "./docs"
}

Paths in entrypoints and outputDir are resolved relative to the config file.

Supported sources

• TypeScript: .ts, .tsx
• Python: .py

Included comment types

• TypeScript: block comments (/* ... */, /** ... */)
• Python: docstrings + # comment blocks opted in with @doc

Use @nodoc on the first line of an included comment to suppress it.

Features

• Markdown rendering for extracted prose
• First included comment first line becomes document <h1>
• One-level appendix inclusion from Markdown links to source files
• Mermaid fenced blocks (```mermaid)
• Local Markdown images inlined as base64 data: URLs
• Tufte CSS typography and layout styling
• Single self-contained HTML output (inline CSS/JS/assets)