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, however it differs on a few points since you are not using an external configuration file. Couple of important points:

1. You can use an external file if you really want, use JSON.parse(fs.readFileSync('/path/to/file.json', 'utf8')) as your options for jsdoc2md.render() / jsdoc2md.renderSync()

2. Once you get to this point you can also decide to move your gulp to using babel as well so you can use ES5 Import. For that rename your gulpfile.js to gulpfile.babel.js and to your package.json add: "babel": {"presets": ["@babel/preset-env"]}

3. Please ensure your documentation works through the CLI as described in How to document TypeScript before adjusting your Gulp configuration.

4. If you cannot get your Gulp to document your TypeScript you can also opt for first compiling it back to JavaScript with the --removeComments=false option for the TypeScript Compiler!

Example usage for Gulp + TypeScript as follows, based on using gulpfile.babel.js as described above

import * as fs from 'fs';
import gulp from 'gulp';
import jsdoc2md from 'jsdoc-to-markdown';

const jsdocOptions = {
    files: './src/*.ts',
    template: fs.readFileSync('./docs/template.hbs', 'utf8'),
    plugins: ['plugins/markdown', 'node_modules/jsdoc-babel'],
    'example-lang': 'nginx',
    noCache: true,
    babel: {
        extensions: ['.ts'],
        ignore: ['**/*.(test|spec).ts', '**/*.js'],
        presets: ['@babel/preset-env', '@babel/preset-typescript'],
        plugins: ['@babel/proposal-class-properties', '@babel/proposal-object-rest-spread'],
        babelrc: false
    },
};

gulp.task('docs', (done) => {
    const docs = jsdoc2md.renderSync(jsdocOptions);
    fs.writeFileSync('./docs/index.md', docs);
    return done();
});