CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-jsdoc-to-markdown

Generates markdown API documentation from JSDoc-annotated source code with comprehensive customization options

Overall
score

97%

Overview
Eval results
Files

cli.mddocs/

Command Line Interface

Comprehensive CLI tool for generating markdown documentation from JSDoc-annotated JavaScript source code. The CLI provides all programmatic API functionality plus additional modes and configuration options.

Capabilities

Basic Command Usage

Generate markdown documentation from JavaScript files using the jsdoc2md command.

# Basic usage with files
jsdoc2md <files...>

# Using glob patterns
jsdoc2md "src/**/*.js"

# Multiple files
jsdoc2md file1.js file2.js lib/*.js

Usage Examples:

# Generate docs from all JS files in src directory
jsdoc2md src/*.js

# Process specific files
jsdoc2md index.js lib/utils.js lib/helpers.js

# Use glob patterns for complex file selection
jsdoc2md "src/**/*.js" "!src/**/*.test.js"

Output Modes

The CLI supports multiple output modes for different use cases.

# Standard markdown output (default)
jsdoc2md [options] <files>

# JSON template data output
jsdoc2md [options] <files> --json

# Raw JSDoc data output  
jsdoc2md [options] <files> --jsdoc

# Namepath information output
jsdoc2md [options] <files> --namepaths

Usage Examples:

# Generate markdown documentation
jsdoc2md src/*.js > docs/API.md

# Get JSON template data for custom processing
jsdoc2md src/*.js --json > template-data.json

# Get raw JSDoc data for analysis
jsdoc2md src/*.js --jsdoc > jsdoc-data.json

# Get namepath information
jsdoc2md src/*.js --namepaths > namepaths.json

Documentation Formatting Options

Control the appearance and structure of generated markdown.

# Heading depth control
jsdoc2md [files] --heading-depth <number>

# Example code language
jsdoc2md [files] --example-lang <language>

# Formatting options
jsdoc2md [files] --name-format --separators --no-gfm

# Index formatting
jsdoc2md [files] --module-index-format <format> --global-index-format <format>

# List formatting
jsdoc2md [files] --param-list-format <format> --property-list-format <format>

# Link formatting
jsdoc2md [files] --clever-links --monospace-links

Usage Examples:

# Set heading depth and example language
jsdoc2md src/*.js --heading-depth 1 --example-lang javascript

# Format identifiers as code and add separators
jsdoc2md src/*.js --name-format --separators

# Disable GitHub-flavored markdown
jsdoc2md src/*.js --no-gfm

# Customize index and list formats
jsdoc2md src/*.js --module-index-format table --param-list-format list

# Configure link rendering
jsdoc2md src/*.js --clever-links

Template Customization

Use custom templates and plugins to control output generation.

# Custom template file
jsdoc2md [files] --template <template-file>

# Plugin support
jsdoc2md [files] --plugin <plugin-name>

# Helper and partial files
jsdoc2md [files] --helper <helper-file> --partial <partial-file>

Usage Examples:

# Use custom Handlebars template
jsdoc2md src/*.js --template custom-template.hbs

# Use a plugin for additional helpers
jsdoc2md src/*.js --plugin dmd-plugin-enhanced

# Add custom helpers and partials
jsdoc2md src/*.js --helper custom-helpers.js --partial custom-partials.hbs

# Combine multiple customizations
jsdoc2md src/*.js --template my-template.hbs --plugin my-plugin --helper helpers.js

Input Source Options

Specify input sources in different ways beyond file paths.

# Source code from stdin or string
jsdoc2md --source <source-code>

# JSDoc configuration file
jsdoc2md --configure <config-file>

# File input (default)
jsdoc2md --files <files...>

Usage Examples:

# Process source code directly
jsdoc2md --source "/**
 * Add two numbers
 * @param {number} a
 * @param {number} b  
 * @returns {number}
 */
function add(a, b) { return a + b; }"

# Use JSDoc configuration file
jsdoc2md --configure jsdoc.conf.json

# Explicit file specification
jsdoc2md --files src/index.js src/utils.js

Cache and Configuration Management

Control caching behavior and view configuration.

# Cache control
jsdoc2md [options] --no-cache
jsdoc2md --clear

# Configuration inspection
jsdoc2md --config

# Help and version
jsdoc2md --help
jsdoc2md --version

Usage Examples:

# Disable caching for this run
jsdoc2md src/*.js --no-cache

# Clear the cache
jsdoc2md --clear

# View current configuration
jsdoc2md --config

# Get help
jsdoc2md --help

# Check version
jsdoc2md --version

CLI Options Reference

JSDoc Options

Options for controlling JSDoc parsing and input sources.

--files, -f <files...>        # Files or glob patterns to process
--source <code>               # Source code string to process  
--configure, -c <file>        # Path to JSDoc configuration file
--namepaths                   # Print namepaths only

jsdoc2md Options

Main tool options affecting operation mode and behavior.

--help, -h                    # Print usage information
--config                      # Print all supplied options and exit
--json                        # Print template data (jsdoc-parse output)
--jsdoc                       # Print raw JSDoc data
--version                     # Print version number
--no-cache                    # Disable caching for this invocation
--clear                       # Clear the cache and exit

DMD (Output) Options

Options controlling markdown output formatting and appearance.

--template, -t <file>         # Custom handlebars template file
--private                     # Include @private identifiers
--heading-depth, -d <number>  # Root heading depth (default: 2)
--plugin <modules...>         # Installed packages with helper/partial overrides
--helper <modules...>         # Handlebars helper modules
--partial <files...>          # Handlebars partial files
--example-lang, -l <lang>     # Default language for @example blocks
--name-format                 # Format identifier names as code
--no-gfm                      # Disable GitHub-flavored markdown
--separators                  # Add <hr> breaks between identifiers
--module-index-format, -m <format>  # Module index style: none, grouped, table, dl
--global-index-format, -g <format>  # Global index style: none, grouped, table, dl
--param-list-format, -p <format>    # Parameter list style: list, table
--property-list-format, -r <format> # Property list style: list, table
--member-index-format <format>      # Member list style: list, grouped
--clever-links                # Render URL links plaintext, others monospace
--monospace-links             # Render all links in monospace
--EOL <type>                  # Line ending type: posix, win32

Configuration Files

The CLI supports configuration files in multiple formats:

package.json Configuration

{
  "jsdoc2md": {
    "files": "src/*.js",
    "heading-depth": 1,
    "example-lang": "javascript",
    "separators": true
  }
}

.jsdoc2md.json Configuration

{
  "files": ["src/index.js", "src/utils.js"],
  "template": "templates/api.hbs",
  "heading-depth": 1,
  "name-format": true,
  "param-list-format": "list"
}

Integration Examples

NPM Scripts Integration

{
  "scripts": {
    "docs": "jsdoc2md src/*.js > docs/API.md",
    "docs:watch": "nodemon --watch src --ext js --exec 'npm run docs'",
    "docs:json": "jsdoc2md src/*.js --json > docs/template-data.json"
  }
}

Build Process Integration

# Generate docs as part of build
npm run build && jsdoc2md dist/*.js > docs/API.md

# Pre-commit hook
#!/bin/sh
jsdoc2md src/*.js > README_API.md
git add README_API.md

Custom Template Usage

# Create custom template
echo '# {{package.name}} API\n{{>main}}' > api-template.hbs

# Use custom template
jsdoc2md src/*.js --template api-template.hbs > API.md

Error Handling

CLI error handling includes comprehensive error messages and exit codes:

  • Exit code 0: Success
  • Exit code 1: Error (file not found, parsing error, etc.)
# Handle errors in scripts
if ! jsdoc2md src/*.js > docs/API.md; then
  echo "Documentation generation failed"
  exit 1
fi

Install with Tessl CLI

npx tessl i tessl/npm-jsdoc-to-markdown

docs

cli.md

index.md

programmatic-api.md

tile.json