How to use with gulp

Base usage

1. Install jsdoc2md in your project.

npm install --save-dev jsdoc-to-markdown

# substitute npm install --save-dev with yarn add -D when using yarn

2. Add a task to your gulpfile.js

• consult the API docs for instructions how to use jsdoc2md.render

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

gulp.task('docs', (done) => {
  jsdoc2md.render({ files: 'lib/*.js' }).then(output => fs.writeFileSync('api.md', output));
  return done();
})

• Or, the synchronous equivalent:

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

gulp.task('docs', (done) => {
  const output = jsdoc2md.renderSync({ files: 'lib/*.js' });
  fs.writeFileSync('api.md', output);
  return done();
})

Specifying options

jsdoc2md.render() and jsdoc2md.renderSync() take an options object as specified in the API docs. Through the options you can specify a template file, the example language and other properties. Example options:

const jsdocOptions = {
    files: './lib/*.js', // specify where your files are
    template: fs.readFileSync('./docs/template.hbs', 'utf8'), // read a template file
    'example-lang': 'nginx', // specify the "@example" code block language
    noCache: true, // Bypass caching
}

Using with TypeScript

Using jsdoc-to-markdown with TypeScript is very similar to How to document TypeScript. It is currently (11th of January 2019) not possible to use the API to document TypeScript (jsdoc-babel has issues properly parsing TypeScript which ends up throwing JSDOC_ERROR: There are no input files to process) directly so we need to apply some extra magic:

1. The example below primarily uses ES5 Import statement but the equivalent require() statements are also included. If you want to use the import variants please rename your gulpfile.js to gulpfile.babel.js and to your package.json add: "babel": {"presets": ["@babel/preset-env"]}.

2. To mirror a similar setup you need these packages:

npm install --save-dev typescript jsdoc-babel @babel/cli @babel/core @babel/preset-env @babel/preset-typescript jsdoc-babel jsdoc-to-markdown @babel/plugin-proposal-class-properties @babel/plugin-proposal-object-rest-spread common-tags

# substitute "npm install --save-dev" with "yarn add -D" when using yarn

3. Example:

import gulp from 'gulp'; // const gulp = require('gulp');
import { exec } from 'child_process'; // const { exec } = require('child_process');
import { oneLine } from 'common-tags'; // const { oneLine } = require('common-tags');

gulp.task('docs', () => {
    const opts = {
        template: './docs/template.hbs',
        exampleLang: 'ts',
        inputFiles: './src/*.ts',
        configFile: './config/jsdoc2md.json',
        outFile: './docs/index.md',
    };
    const docsCommand = oneLine`node ./node_modules/jsdoc-to-markdown/bin/cli.js
        --files ${opts.inputFiles}
        --template ${opts.template}
        --example-lang ${opts.exampleLang}
        --configure ${opts.configFile}
        > ${opts.outFile}`;
    return exec(docsCommand);
});

What does this task do?

• We're importing exec from NodeJS. exec spawns a child process with whatever input we feed it, in this case we execute ./node_modules/jsdoc-to-markdown/bin/cli.js with node
• We're importing oneLinefromcommon-tags` to make the command more human readable
• To use this template you can copy it and modify the opts to your project
  • Create a jsdoc2md.json file as described in How to document TypeScript
  • set inputFiles to the path where your TypeScript files are
  • set template to your *.hbs jsdoc2md template, if you have none remove it from the docsCommand
  • set exampleLang to the language you want your @example tags to be shown as
  • set configFile to the path to your jsdoc2md.json configuration file