or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdindex.mdprogrammatic-api.md
tile.json

tessl/npm-jsdoc-to-markdown

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/jsdoc-to-markdown@9.1.x

To install, run

npx @tessl/cli install tessl/npm-jsdoc-to-markdown@9.1.0

index.mddocs/

JSDoc to Markdown

JSDoc to Markdown is a comprehensive tool for generating markdown API documentation from JSDoc-annotated JavaScript source code. It serves as a bridge between JSDoc comments in source files and markdown documentation, making it particularly useful for injecting API documentation into project README files and maintaining up-to-date documentation. The library offers both programmatic API access and command-line interface, supporting various output formats and customization options.

Package Information

  • Package Name: jsdoc-to-markdown
  • Package Type: npm
  • Language: JavaScript (ES modules)
  • Installation: npm install --save-dev jsdoc-to-markdown

Core Imports

import jsdoc2md from 'jsdoc-to-markdown';

For CommonJS:

const jsdoc2md = require('jsdoc-to-markdown');

Basic Usage

import jsdoc2md from 'jsdoc-to-markdown';

// Generate markdown from JavaScript files
const apiDocs = await jsdoc2md.render({ files: 'lib/*.js' });

// Generate from source code string
const apiDocs = await jsdoc2md.render({
  source: `
    /**
     * A wonderful function.
     * @param {object} config - Configuration object
     * @returns {string} Formatted output
     */
    function formatData(config) {
      return 'formatted';
    }
  `
});

// Get raw JSDoc data
const jsdocData = await jsdoc2md.getJsdocData({ files: 'src/*.js' });

// Get template data for custom processing
const templateData = await jsdoc2md.getTemplateData({ files: 'src/*.js' });

Architecture

JSDoc to Markdown is built around several key components:

  • Core API: Main JsdocToMarkdown class providing all functionality through a singleton instance
  • JSDoc Integration: Leverages jsdoc-api for parsing JSDoc annotations
  • Template Engine: Uses dmd (Documentation Markdown) for rendering markdown output
  • CLI Interface: Full-featured command-line tool with extensive configuration options
  • Caching System: Built-in caching for improved performance on repeated invocations
  • Option Processing: Separate classes for handling different configuration contexts

Capabilities

Programmatic API

Core programmatic interface for generating markdown documentation from JSDoc-annotated source code. Provides methods for rendering, data extraction, and cache management.

async function render(options?: RenderOptions): Promise<string>;
async function getTemplateData(options?: TemplateDataOptions): Promise<object[]>;
async function getJsdocData(options: JsdocDataOptions): Promise<object[]>;
async function clear(): Promise<void>;
async function getNamepaths(options: NamepathOptions): Promise<object>;

Programmatic API

Command Line Interface

Comprehensive CLI tool for generating documentation with extensive configuration options, multiple output formats, and configuration file support.

# Basic usage
jsdoc2md src/*.js

# With options
jsdoc2md --files src/*.js --heading-depth 1 --template custom.hbs

# Different output modes
jsdoc2md --files src/*.js --json          # Raw template data
jsdoc2md --files src/*.js --jsdoc         # Raw JSDoc data
jsdoc2md --files src/*.js --namepaths     # Namepath information

Command Line Interface

Types

interface RenderOptions extends TemplateDataOptions {
  /** Raw template data to use instead of parsing files */
  data?: object[];
  /** Custom handlebars template for full control over output */
  template?: string;
  /** Initial heading depth (default: 2) */
  'heading-depth'?: number;
  /** Default language for @example blocks */
  'example-lang'?: string;
  /** Installed package containing helper/partial overrides */
  plugin?: string | string[];
  /** Handlebars helper files to override defaults */
  helper?: string | string[];
  /** Handlebars partial files to override defaults */
  partial?: string | string[];
  /** Format identifier names as code (wrap in backticks) */
  'name-format'?: boolean;
  /** Disable GitHub-flavored markdown */
  'no-gfm'?: boolean;
  /** Add horizontal rule breaks between identifiers */
  separators?: boolean;
  /** Module index format: none, grouped, table, dl */
  'module-index-format'?: string;
  /** Global index format: none, grouped, table, dl */
  'global-index-format'?: string;
  /** Parameter list format: list, table */
  'param-list-format'?: string;
  /** Property list format: list, table */
  'property-list-format'?: string;
  /** Member index format: grouped, list */
  'member-index-format'?: string;
  /** Render URL links in plain text, others in monospace */
  'clever-links'?: boolean;
  /** Render all links in monospace */
  'monospace-links'?: boolean;
  /** EOL character: posix, win32 */
  EOL?: string;
}

interface TemplateDataOptions extends JsdocDataOptions {}

interface JsdocDataOptions {
  /** Disable caching for this invocation */
  'no-cache'?: boolean;
  /** File paths or glob patterns to process */
  files?: string | string[];
  /** Source code string to process */
  source?: string;
  /** Path to JSDoc configuration file */
  configure?: string;
}

interface NamepathOptions extends TemplateDataOptions {}