grunt-jsdoc2md

grunt-jsdoc2md

grunt-jsdoc2md uses the third-party tool jsdoc-to-markdown, to convert jsdoc annotations to markdown.

grunt-jsdoc2md generates a markdown file for each sourcefile. Additionally it creates a markdown index file, which links the subsequent markdown module files.

grunt-jsdoc2md takes on the role of passing configuration parameters from grunt to jsdoc-to-markdown.

grunt

is a task runner written in Javascript that can be used to build projects. For this purpose grunt integrates plugins that contribute to the build process with their different capabilities.

grunt-jsdoc2md is open source software (OSS) and distributed under the MIT License.

Third party tools:

jsdoc-to-markdown is open source software (OSS) and distributed under the MIT License.

Prerequisites for installing grunt-jsdoc2md are an existing npm that ships with nodejs and grunt.

npm install grunt-jsdoc2md --save-dev

grunt-jsdoc2md on npmjs.com

Configuration of the plugin is usually done via an entry in the grunfile.js file. To be able to keep an overview of the configuration even when using many plugins, we use the package load-grunt-config. This way we can keep a separate configuration file for each plugin, as the following example shows.

// file jsdoc2md.js
module.exports = function ( grunt, options ) {
  return {
    options: {
      // options to use with every target
      // basically all options, which are accepted by
      // 'jsdoc-to-markdown', can be added here.
    },
    target1: {
      // multiple source files to directory with multiple markdown files
      src: "src/lib/**/*.js",         // glob which will resolve to multiple sourcefiles
      dest: "docs/api/",              // destination 'directory' (defined by ending slash)
                                      // ... this is where the markdown files will be created.
      options: {                      // options to use with 'target0'
        index:  {                     // create an index file
          dest:     "docs/api.md"     // name it 'api.md' and place it in the docs directory.
          // template: "partials/api.hbs"   // use the named template to create the index file.
        }
      }
    },
    target2: {
      files: [
        // single source file to single markdown file
        { src: 'src/lib/tasks/jsdoc2md.js',   dest: 'src/test/tmp/api/tofile/1/jsdoc2md.md'       },
        // missing source file ... producing no output but a warning message
        { src: 'src/does.not.exist.js',       dest: 'src/test/tmp/api/tofile/2/missing.src.md'    },
        // multiple source files to single (aggregated) markdown file
        { src: 'src/lib/**/*.js',             dest: 'src/test/tmp/api/tofile/3/aggregated.api.md' },
        // multiple source files to directory creating multiple markdown files
        { src: 'src/lib/**/*.js',             dest: 'src/test/tmp/api/tofile/4/' },
        // multiple source files to directory creating multiple markdown files
        { src: 'src/test/templates/**/*.js',  dest: 'src/test/tmp/api/tofile/5/' }
      ]
    }
  };
};

grunt-jsdoc2md