gulp-jsdoc-to-markdown

Plugin for jsdoc-to-markdown. Works in both buffer and streaming modes.

Caveat

If you intend to use this plugin and your code has modules, you must always supply a name with the @module tag.

In other words @module will fail, @module my-module will win.

If the module name is not provided, jsdoc will try to infer it from the filename of the module. However, gulp deals with streams - not files. And that stream could come from anywhere. We do not know the file name so we cannot infer the module name - so always supply it. More info here.

gulpfile.js examples

One markdown file out per source file in

'use strict'
var fs = require('fs')
var gulp = require('gulp')
var gutil = require('gulp-util')
var gulpJsdoc2md = require('gulp-jsdoc-to-markdown')
var rename = require('gulp-rename')
var concat = require('gulp-concat')

gulp.task('docs', function () {
  return gulp.src('lib/*.js')
    .pipe(gulpJsdoc2md({ template: fs.readFileSync('./readme.hbs', 'utf8') }))
    .on('error', function (err) {
      gutil.log(gutil.colors.red('jsdoc2md failed'), err.message)
    })
    .pipe(rename(function (path) {
      path.extname = '.md'
    }))
    .pipe(gulp.dest('api'))
})

Multiple source files in, a single markdown file out

'use strict'
var fs = require('fs')
var gulp = require('gulp')
var gutil = require('gulp-util')
var gulpJsdoc2md = require('gulp-jsdoc-to-markdown')
var concat = require('gulp-concat')

gulp.task('docs', function () {
  return gulp.src('lib/*.js')
    .pipe(concat('all.md'))
    .pipe(gulpJsdoc2md({ template: fs.readFileSync('./readme.hbs', 'utf8') }))
    .on('error', function (err) {
      gutil.log('jsdoc2md failed:', err.message)
    })
    .pipe(gulp.dest('api'))
})

Install

Install this plugin:

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

If using one of the example gulpfiles above you will also need to run:

$ npm i gulp gulp-util gulp-concat gulp-rename --save-dev

© 2014-16 Lloyd Brookes <[email protected]>.