BOTTOM AI CHANGELOG LICENSE

grunt-jsdoc2md

Generate structured Markdown API documentation from JSDoc using jsdoc-to-markdown,
with deterministic tree rendering and optional automatic API index generation.

content

• Usage (see further down this page)
  • Getting started guide
  • Usage and examples
  • Rendering modes
  • API index generation
  • Deterministic rendering semantics
  • Maybe look at the projects config?
• Developers
  • Testing grunt-jsdoc2md
  • Code coverage of tests for grunt-jsdoc2md
  • Build grunt-jsdoc2md from scratch
  • NPM integration of grunt-jsdoc2md
  • Frameworks used for testing, building, etc.
  • API of package grunt-jsdoc2md (self generated with grunt-jsdoc2md)

Changelog
Details on AI assistance during development

Overview

grunt-jsdoc2md is a Grunt multitask that transforms one or more JSDoc-annotated JavaScript source files into Markdown documentation.

The plugin adds structural capabilities on top of jsdoc-to-markdown:

• Deterministic depth-first tree rendering
• Automatic directory structure generation
• Optional aggregated API index generation
• Sequential fail-fast execution semantics
• Integrated dmd-readable defaults

Requirements

• Node.js >= 20
• Grunt >= 1.x

Installation

npm install grunt-jsdoc2md --save-dev

Load the plugin in your Gruntfile.js:

grunt.loadNpmTasks("grunt-jsdoc2md");

Run the task:

grunt jsdoc2md

getting started

This guide assumes familiarity with npm and Grunt.

Minimal configuration example:

module.exports = function (grunt) {
  grunt.initConfig({
    jsdoc2md: {
      api: {
        src: "src/**/*.js",
        dest: "docs/api/"
      }
    }
  });

  grunt.loadNpmTasks("grunt-jsdoc2md");
};

Running grunt jsdoc2md generates Markdown documentation in docs/api/.

usage

The plugin supports two execution modes depending on dest.

module.exports = function (grunt) {
  return {
    options: {
      // All jsdoc-to-markdown options are supported.
    },

    directoryExample: {
      src: "src/lib/**/*.js",
      dest: "docs/api/",
      options: {
        index: {
          dest: "docs/api.md"
          // template: "partials/api.hbs"
        }
      }
    },

    fileExample: {
      src: "src/lib/**/*.js",
      dest: "docs/aggregated-api.md"
    }
  };
};

Rendering modes

Directory Mode

If dest:

• already exists and is a directory, or
• ends with / or \

each source file is rendered into a corresponding Markdown file.

A directory tree is constructed from the source paths.

Example:

src/lib/index.js
src/lib/utils/helper.js

Produces:

docs/api/index.md
docs/api/utils/helper.md

Rendering is:

• Depth-first
• Strictly sequential per node
• Deterministic in output order

Optional index generation is supported.

File Mode

If dest is a file path, all source files are rendered into a single aggregated Markdown file.

No directory tree is created.

API index generation

If options.index !== false, an aggregated API index file is generated.

options: {
  index: {
    dest: "docs/api.md",
    template: "partials/api.hbs" // optional
  }
}

Behavior:

• All rendered fileset data is aggregated
• A template is applied
• Default template: {{>api}}
• Rendering is deterministic
• Fail-fast on error

If options.index === false, no index file is created.

Deterministic rendering semantics

The plugin enforces:

• Sequential file rendering within each node
• Depth-first tree traversal
• Stable aggregation order
• Fail-fast behavior on errors

This ensures reproducible documentation output across environments.

Error handling

• Missing src → warning
• Rendering failure → task failure
• Index generation failure → task failure

No partial recovery is attempted.

Notes

Handlebars may cache compiled templates during development. If template changes are not reflected, clear your system temp directory.

TOP AI CHANGELOG LICENSE