Quick Start

Generate your first documentation with doc-kit in minutes

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:

   Basic

   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:

Generator	Description	Use Case
legacy-html	Traditional Node.js HTML format	Legacy compatibility
legacy-html-all	Single-file HTML with all APIs	Offline browsing
legacy-json	Structured JSON format	Tooling integration
legacy-json-all	Single JSON file with all APIs	Data processing
web	Modern redesigned web pages	Modern documentation sites
orama-db	Search index database	Enable search in web format
man-page	Unix manual pages	Command-line reference
json-simple	Simplified JSON structure	Custom integrations
llms-txt	LLM-optimized text	AI/LLM consumption
api-links	API link verification	Quality assurance
addon-verify	Addon verification	Validate 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:

Legacy format

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