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 Documented source code in, markdown out.. In development, any feedback welcome.

##Install Ensure node.js is installed first. Linux/Mac users may need to run the following commands with sudo.

###Globally

$ npm install -g jsdoc-to-markdown

###Bundled with your project In my opinion, this is the most efficient solution (no task runner required).

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

Then add an docs build task to your package.json scripts, e.g.:

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

Docs are generated like so:

$ npm run docs

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

###As a gulp plug-in Use a task like this until the gulp plugin is ready, you should only need to edit src and outputFile:

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 outputFile = "api.md";
    gutil.log("writing documentation to " + outputFile);
    jsdoc2md.render(src).pipe(fs.createWriteStream(outputFile));
});

##Usage Document your source code using correct jsdoc syntax, then run it through jsdoc2md. If no <source_files> are supplied it will look for doclet data on stdin.

$ jsdoc2md [<options>] [<source_files>]
$ cat doclets.json | jsdoc2md [<options>]

-t, --template <string>   A custom handlebars template to insert the rendered documentation into,
                          overriding the default
-p, --preset <string>     Use a preset template ('default', 'global' or 'modules')
-j, --json                Output the template data only
-h, --help                Print usage information
--src <array>             The javascript source files. The default option.
--private                 Include symbols marked @private in the output
--heading-depth <number>  root heading depth to begin the documentation from, defaults to 2 (`##`).

##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)

##Templating Running jsdoc2md without a --template generates documentation with the default template, which looks like this:

{{>index}}
{{>modules}}
{{>globals}}
{{>others}}

###{{>index}} Only output if there are at least two modules defined.

#Index

* Modules
  * {{>module-name}}
    * {{>member-names}}
* Global
  * {{>global-name}}

###{{>modules}} Outputs one {{>module}} partial per module.

###{{>globals}}

#Global
{{>global-index}}
{{>members}}

###{{>members}}

{{#each (members in=data)}}{{>member}}{{/each~}} {{#each (functions in=data)}}{{>function}}{{/each~}} {{#each (namespaces in=data)}}{{>namespace}}{{/each~}} {{#each (constants in=data)}}{{>constant}}{{/each~}} {{#each (typedefs in=data)}}{{>typedef}}{{/each~}} {{#each (events in=data)}}{{>event}}{{/each~}} {{#each (classes in=data)}}{{>class}}{{/each~}}

###{{>module}}

{{>module-head}}
{{>module-body}}
{{>module-exported}}  (either a class with index, function or object with index)

###{{>module-head}}

{{>anchor}}
{{>heading}}{{>module-name}}

###{{>module-body}}

{{>fields}}

###{{>fields}}

{{>description~}}
{{>params~}}
{{>deprecated~}}
{{>augments~}}
{{>memberof~}}
{{>type~}}
{{>default~}}
{{>returns~}}
{{>access~}}
{{>enum~}}
{{>readOnly~}}
{{>since~}}
{{>version~}}
{{>authors~}}
{{>license~}}
{{>copyright~}}
{{>examples~}}

###{{>module-exported}}

{{>class}}, {{>function}} or {{>module-index}} and {{>members}}

###{{>class}}

{{>class-head}}
{{>class-body~}}
{{>class-members-index~}}
{{>class-members~}}

##API Reference Example

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

Members

• jsdoc2md.render(sourceFiles, options)
• jsdoc2md.createRenderStream(options)

##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.
  • [preset] string - Choose from one of the built-in templates
  • [json] boolean - Return the JSON template data only
  • [private] boolean - Include symbols marked @private in the output
  • [heading-depth] number - Root heading depth, defaults to 2.

Returns: stream - A readable stream containing the rendered markdown
Example
this code:

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

generates:

#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.
  - [preset] `string` - Choose from one of the built-in templates
  - [json] `boolean` - Return the JSON template data only
  - [private] `boolean` - Include symbols marked @private in the output
  - [heading-depth] `number` - Root heading depth, defaults to 2.
**Returns**: `stream` - A readable stream containing the rendered markdown

etc.
etc.

##jsdoc2md.createRenderStream(options) Params

• options object - The render options, as specified in render()

Returns: stream - a stream containing the rendered markdown
Example

process.stdin
    .pipe(jsdoc2md.createRenderStream({ template: "api.hbs" }))
    .pipe(process.stdout);