dmd-grunt-jsdoc2md

A dmd template extension for grunt-jsdoc2md that generates a global, navigable API index across multiple Markdown files produced from JSDoc.

This package does not generate documentation by itself. Instead, it extends the dmd render phase with additional helpers and Handlebars partials that operate on the complete JSDoc symbol model.

Contents

• Getting started
• Concept and scope
• Usage
• What this package does not do

See also: Changelog

Getting started

This guide assumes familiarity with npm, Grunt, and JSDoc-based documentation workflows.

Install the package as a development dependency:

npm install dmd-grunt-jsdoc2md --save-dev

This package is designed to be used together with grunt-jsdoc2md, which must already be part of your build setup.

Concept and scope

When using grunt-jsdoc2md, it is common to generate one Markdown file per source file. While this scales well for larger codebases, it leaves the generated documentation without a single, global entry point.

dmd-grunt-jsdoc2md addresses this gap by providing:

• additional dmd helpers
• a set of Handlebars partials

that are executed during the dmd render phase. These templates have access to the entire JSDoc symbol model and can therefore generate a global API index that links all generated Markdown files together.

The index is symbol-based (modules and their members), not file-based, and relies entirely on the metadata and link targets already provided by dmd and jsdoc-to-markdown.

Usage

dmd-grunt-jsdoc2md is used implicitly by grunt-jsdoc2md when configured to generate an index file.

Example source structure:

--+ src
  + file1.js
  + file2.js
  + subdir1
  |  + subdir1file1.js
  |
  + subdir2
     + subdir2file1.js

Corresponding grunt-jsdoc2md configuration (excerpt from Gruntfile.js):

{
  "jsdoc2md": {
    "target0": {
      "src": "src/**/*.js",
      "dest": "docs/apidir/",
      "options": {
        "index": {
          "dest": "docs/api.md"
        }
      }
    }
  }
}

This configuration results in:

--+ docs
  + api.md          <= global API index
  |
  + apidir          <= per-file API documentation
    + file1.md
    + file2.md
    + subdir1
    |  + subdir1file1.md
    |
    + subdir2
       + subdir2file1.md

During the render process:

1. grunt-jsdoc2md builds the complete JSDoc symbol model.
2. Per-file Markdown documents are rendered.
3. dmd renders an additional index template provided by this package.
4. The resulting api.md links to all documented modules and their members.

The index can be rendered in different formats (grouped, list-based, or tabular), depending on the configured dmd options.

What this package does not do

To avoid misunderstandings, this package intentionally does not:

• parse source code
• collect or aggregate JSDoc metadata itself
• generate or post-process Markdown files
• manage file paths or links manually

All links, anchors, and symbol relationships are derived directly from dmd and jsdoc-to-markdown.

In short, dmd-grunt-jsdoc2md is a focused dmd extension that leverages the global render context to provide a single, navigable API index for multi-file JSDoc-based documentation.