Skip to main content

​
Quick Start

This guide will walk you through generating your first documentation with doc-kit. You’ll learn the basic workflow and see real examples of different output formats.

​
Basic Usage

The simplest way to generate documentation: 
npx @nodejs/doc-kit generate -i "docs/api/*.md" -o out -t legacy-html
This command:
  • Reads all markdown files matching docs/api/*.md
  • Generates HTML documentation using the legacy format
  • Outputs files to the out directory

​
Generate Legacy HTML Documentation

To create a 1:1 match with the traditional Node.js documentation format:
1

Prepare your markdown files

Organize your API documentation in markdown format:
docs/
└── api/
    ├── index.md
    ├── fs.md
    ├── http.md
    └── path.md
2

Run the generator

Generate both HTML and JSON output:
npx @nodejs/doc-kit generate \
  -t legacy-html \
  -t legacy-json \
  -i "docs/api/*.md" \
  -o out
3

View the output

Your generated documentation will be in the out directory:
out/
├── fs.html
├── fs.json
├── http.html
├── http.json
├── path.html
└── path.json

​
Generate Modern Web Documentation

Create redesigned documentation pages with built-in search:
1

Generate web output with search

Use the web and orama-db generators:
npx @nodejs/doc-kit generate \
  -t web \
  -t orama-db \
  -i "docs/api/*.md" \
  -o out \
  --index docs/api/index.md
The orama-db generator creates a search index. You must include it if you want search functionality.
2

Serve the documentation

The web generator creates a static site that needs to be served:
npx serve out
Then open your browser to http://localhost:3000 to view the documentation.
The modern web format includes syntax highlighting, responsive design, and a powerful search interface powered by Orama.

​
Generate Man Pages

Create Unix manual pages for command-line reference: 
npx @nodejs/doc-kit generate \
  -t man-page \
  -i "docs/api/*.md" \
  -o out
View the generated man page: 
man out/fs.1

​
Available Generator Targets

You can use the -t or --target flag to specify one or more output formats:
GeneratorDescriptionUse Case
legacy-htmlTraditional Node.js HTML formatLegacy compatibility
legacy-html-allSingle-file HTML with all APIsOffline browsing
legacy-jsonStructured JSON formatTooling integration
legacy-json-allSingle JSON file with all APIsData processing
webModern redesigned web pagesModern documentation sites
orama-dbSearch index databaseEnable search in web format
man-pageUnix manual pagesCommand-line reference
json-simpleSimplified JSON structureCustom integrations
llms-txtLLM-optimized textAI/LLM consumption
api-linksAPI link verificationQuality assurance
addon-verifyAddon verificationValidate C++ addons

​
Common CLI Options

Here are the most frequently used options:

​
Input and Output

# Input patterns (glob)
-i, --input <patterns...>

# Output directory
-o, --output <dir>

# Ignore patterns
--ignore <patterns...>

​
Version and References

# Target Node.js version (default: "v22.14.0")
-v, --version <semver>

# Changelog URL or path
-c, --changelog <url>
# Default: https://raw.githubusercontent.com/nodejs/node/HEAD/CHANGELOG.md

# Git ref/commit URL
--git-ref <url>
# Default: https://github.com/nodejs/node/tree/HEAD

​
Performance

# Number of parallel threads (default: 12)
-p, --threads <number>

​
Example with all options

npx @nodejs/doc-kit generate \
  -i "docs/api/*.md" \
  --ignore "docs/api/deprecated/*.md" \
  -o dist/docs \
  -t web \
  -t orama-db \
  -v "v20.0.0" \
  -p 8 \
  --index docs/api/index.md

​
Real-World Example: Node.js Repository

If you have a clone of the Node.js repository, you can generate its documentation: 
npx @nodejs/doc-kit generate \
  -t legacy-html \
  -t legacy-json \
  -i "path/to/node/doc/api/*.md" \
  -o out \
  --index path/to/node/doc/api/index.md

​
Using Configuration Files

For complex setups, create a configuration file:
1

Create doc-kit.config.mjs

doc-kit.config.mjs
export default {
  global: {
    version: '20.0.0',
    minify: true,
    input: ['docs/api/*.md'],
    output: 'dist/docs',
    ignore: ['docs/api/deprecated/**'],
    changelog: 'https://raw.githubusercontent.com/nodejs/node/main/CHANGELOG.md',
    index: 'docs/api/index.md',
  },
  
  threads: 8,
  chunkSize: 10,
  
  // Generator-specific config
  'legacy-json': {
    minify: false,
  },
};
2

Run with config file

npx @nodejs/doc-kit generate \
  --config-file doc-kit.config.mjs \
  -t web \
  -t orama-db
Configuration files can be JavaScript (.mjs, .js with "type": "module") or JSON (.json) format.

​
Next Steps

Now that you’ve generated your first documentation:

Configuration

Learn about advanced configuration options

Generators

Explore all available generators in detail

CLI Commands

Master all CLI commands and options

Custom Generators

Build your own custom generators

Build docs developers (and LLMs) love

Get started for freeTalk to us