jsdoc-to-markdown

What is jsdoc-to-markdown?

The jsdoc-to-markdown npm package is a tool that generates markdown documentation from JSDoc comments in your JavaScript code. It is useful for creating comprehensive and readable documentation for your projects.

What are jsdoc-to-markdown's main functionalities?

Generate Markdown Documentation

This feature allows you to generate markdown documentation from JSDoc comments in your JavaScript files. The code sample demonstrates how to use jsdoc-to-markdown to read JSDoc comments from JavaScript files in the 'src' directory and output the generated markdown to 'docs/api.md'.

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

const inputFiles = 'src/**/*.js';
const outputFile = 'docs/api.md';

jsdoc2md.render({ files: inputFiles })
  .then(output => fs.writeFileSync(outputFile, output));

Customizing the Output

This feature allows you to customize the output of the generated markdown documentation using a template. The code sample shows how to use a custom template to format the documentation for a specific module.

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

const inputFiles = 'src/**/*.js';
const outputFile = 'docs/api.md';

const template = `{{#module name="myModule"}}{{>docs}}{{/module}}`;

jsdoc2md.render({ files: inputFiles, template: template })
  .then(output => fs.writeFileSync(outputFile, output));

Filtering Output

This feature allows you to filter the output of the generated markdown documentation. The code sample demonstrates how to disable GitHub Flavored Markdown (GFM) in the output by setting the 'no-gfm' option to true.

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

const inputFiles = 'src/**/*.js';
const outputFile = 'docs/api.md';

jsdoc2md.render({ files: inputFiles, 'no-gfm': true })
  .then(output => fs.writeFileSync(outputFile, output));

Other packages similar to jsdoc-to-markdown

documentation

The 'documentation' package is another tool for generating documentation from JSDoc comments. It offers a command-line interface and supports various output formats, including HTML and JSON. Compared to jsdoc-to-markdown, 'documentation' provides more flexibility in terms of output formats but may require more configuration.

jsdoc

The 'jsdoc' package is a popular tool for generating HTML documentation from JSDoc comments. It is highly configurable and supports a wide range of tags and plugins. While 'jsdoc' focuses on generating HTML documentation, jsdoc-to-markdown is specialized in generating markdown documentation, making it more suitable for projects that prefer markdown.

esdoc

The 'esdoc' package is a documentation generator for JavaScript that supports ES6+ syntax. It generates HTML documentation and includes features like coverage reports and test integration. Compared to jsdoc-to-markdown, 'esdoc' is more focused on modern JavaScript syntax and provides additional features like coverage reports.

README

work in progress, unstable, draft documentation

#jsdoc-to-markdown jsdoc documented source code in, markdown out.

This module connects the output of jsdoc-parse to the input of dmd. For information about the markdown output, customising templates etc. please read the dmd docs.

##Synopsis write documented code:

/**
a quite wonderful function
@param {object} - privacy gown
@param {object} - security
@returns {survival}
*/
function protection(cloak, dagger){}

get markdown docs:

$ jsdoc2md example/function.js

#protection(cloak, dagger)
a quite wonderful function

**Params**

- cloak `object` - privacy gown
- dagger `object` - security

**Returns**: `survival`

this command achieves the same result:

$ jsdoc-parse example/function.js | dmd

##Examples These projects have readme files rendered by jsdoc2md:

• handbrake-js (exports an object with inner class)
• array-tools (exports a object)
• file-set (exports a class)
• command-line-args (exports a class)

##Compatible Platforms Tested on Mac OSX, Linux, Windows 8.1 and Windows XP.

##Usage Document your source code using correct jsdoc syntax, then run it through jsdoc2md.

###Command-line tool Install jsdoc2md globally:

$ npm install -g jsdoc-to-markdown

Options:

$ jsdoc2md -h

  jsdoc-to-markdown
  Markdown API documentation generator, good for Github projects

  Usage
  $ jsdoc2md [<options>] <source_files>

  --src <array>             A list of javascript source files or glob expressions
  -t, --template <string>   A custom handlebars template to insert the rendered documentation into
  -j, --json                Output the parsed jsdoc data only
  -v, --verbose             More verbose error reporting
  -h, --help                Print usage information
  --private                 Include symbols marked @private in the output
  -s, --stats               Print a few stats about the doclets parsed.
  --heading-depth <number>  root heading depth to begin the documentation from, defaults to 1 (`#`).
  -p, --plugin <array>      Use an installed package containing helper and/or partial overrides
  --helper <array>          handlebars helper files to override or extend the default set
  --partial <array>         handlebars partial files to override or extend the default set

Some typical use cases:

$ # dump everything you have into a single file
$ jsdoc src/**/*.js > api.md

$ # split into separate files
$ jsdoc src/main-module.js > main-module.md
$ jsdoc src/important-class.js > important-class.md

$ # embed documentation into a template you made
$ jsdoc src/**/*.js --template readme.hbs > README.md

###Bundled with your project ####As an npm run task

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

Then add a docs build script to your package.json, e.g.:

{
  "name": "my-web-app",
  "version": "1.0.0",
  "scripts": {
    "docs": "jsdoc2md lib/*.js > api.md"
  }
}

Docs are generated like so:

$ npm run docs

####As a grunt plug-in See grunt-jsdoc-to-markdown.

####As a gulp task Currently, the most reliable and natural way of using jsdoc2md with gulp. If your source code contains @module tags, use this method only (reason). You should only need to edit src, dest and options:

var jsdoc2md = require("jsdoc-to-markdown");
var gutil = require("gulp-util");
var fs = require("fs");

gulp.task("docs", function(done){
    var src = "lib/**/*.js";
    var dest = "api.md";
    var options = {};
    
    gutil.log("writing documentation to " + dest);
    jsdoc2md.render(src, options)
        .on("error", function(err){
            gutil.log(gutil.colors.red("jsdoc2md failed"), err.message);
        })
        .pipe(fs.createWriteStream(dest));
});

####As a gulp plug-in See gulp-jsdoc-to-markdown.

###Library Example

var jsdoc2md = require("jsdoc-to-markdown");

####jsdoc2md.render(src, options) Transforms jsdoc into markdown documentation.

Params

• src string | Array.<string> - The javascript source file(s).
• options object - The render options
  • [template] string - A custom handlebars template to insert the rendered documentation into.
  • [json] boolean - Output the parsed jsdoc data only
  • [private] boolean - Include symbols marked @private in the output
  • [stats] boolean - Print a few stats about the doclets parsed
  • [heading-depth] number - root heading depth, defaults to 1 (#)
  • [plugin] string | Array.<string> - Use an installed package containing helper and/or partial overrides
  • [helper] string | Array.<string> - handlebars helper files to override or extend the default set
  • [partial] string | Array.<string> - handlebars partial files to override or extend the default set

Returns: stream - A transform stream containing the rendered markdown
Example
Two ways to use render. Either pass in filepaths (** glob matching supported) of javascript source files:

> jsdoc2md.render("lib/*.js").pipe(process.stdout);

or pipe in source code from another source:

> fs.createReadStream("lib/main.js").pipe(jsdoc2md.render()).pipe(process.stdout);

output looks something like:

generates:
```markdown
#jsdoc-to-markdown
**Members**
[jsdoc2md.render(sourceFiles, options)](#module_jsdoc-to-markdown.render)
[jsdoc2md.createRenderStream(options)](#module_jsdoc-to-markdown.createRenderStream)

<a name="module_jsdoc-to-markdown.render"></a>
##jsdoc2md.render(sourceFiles, options)
Renders the jsdoc documentation from the specified source files as markdown.
**Params**

- sourceFiles `string` | `Array.<string>` - The javascript source file(s) - required.
- options `object` - The render options
  - [template] `string` - A handlebars template to insert your documentation into.
  - [json] `boolean` - Return the JSON template data only
  - [stats] `boolean` - Return a few stats about the doclets parsed
  - [private] `boolean` - Include symbols marked @private in the output
  - [heading-depth] `number` - Root heading depth, defaults to 1.
**Returns**: `stream` - A readable stream containing the rendered markdown

etc.
etc.