Home

Awesome

markdown-magic-jsdoc

A plugin for markdown-magic that parses jsdoc style comments as a transform

Install

npm i markdown-magic markdown-magic-jsdoc --save-dev

Adding the plugin

See doc.js for usage.

<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./docs.js) --> <!-- The below code snippet is automatically added from ./docs.js --> 
/* eslint import/no-extraneous-dependencies: ["error", {"devDependencies": true}] */
const path = require('path');
const markdownMagic = require('markdown-magic'); // 'markdown-magic'
const JSDOC = require('./index.js');

const mmdConfig = {
  transforms: {
    /* Match <!-- AUTO-GENERATED-CONTENT:START (JSDOC:files=../docs.js) --> */
    JSDOC,
  },
};

const markdownPath = path.join(__dirname, './', 'README.md');
markdownMagic(markdownPath, mmdConfig);
<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./docs.js) --> <!-- AUTO-GENERATED-CONTENT:END *-->

Usage in markdown

See examples/*.js for usage. For complete documentation on comment structure, please visit https://github.com/jsdoc2md/jsdoc-to-markdown/wiki

Original Comment

/**
 * A module for adding two values.
 * @module add-two-values
 */

/**
 * Add two values.
 */
function add (a, b) {
  return a + b
}

Markdown Output

<!-- AUTO-GENERATED-CONTENT:START (JSDOC:files=./examples/module.js) -->

<a name="module_add-two-values"></a>

add-two-values

A module for adding two values.

<a name="module_add-two-values..add"></a>

add-two-values~add()

Add two values.

Kind: inner method of <code>add-two-values</code>

<!-- AUTO-GENERATED-CONTENT:START (JSDOC:files=./examples/module.js) --> <!-- AUTO-GENERATED-CONTENT:END *-->

Options

This module does not support all of the options for jsdoc-to-markdown. Create a PR if you want to add an option

<!-- AUTO-GENERATED-CONTENT:START (JSDOC:files=./index.js) -->

<a name="defaults"></a>

defaults

Returns markdown documentation from jsdoc-annoted source code.

Kind: global constant

ParamTypeDescription
files<code>Array.<object></code>full path to the local javascript file that has the jsdoc comment
heading-depth<code>number</code>The initial heading depth. For example, with a value of 2 the top-level markdown headings look like "## The heading".
no-gfm<code>boolean</code>By default, dmd generates github-flavoured markdown. Not all markdown parsers render gfm correctly. If your generated docs look incorrect on sites other than Github (e.g. npmjs.org) try enabling this option to disable Github-specific syntax.
separators<code>boolean</code>Put <hr> breaks between identifiers. Improves readability on bulky docs.
module-index-format<code>string</code>none, grouped, table, dl.
global-index-format<code>string</code>none, grouped, table, dl.
param-list-format<code>string</code>Two options to render parameter lists: 'list' or 'table' (default). Table format works well in most cases but switch to list if things begin to look crowded / squashed.
property-list-format<code>string</code>list, table.
member-index-format<code>string</code>grouped, list
<!-- AUTO-GENERATED-CONTENT:START (JSDOC:files=./index.js) --> <!-- AUTO-GENERATED-CONTENT:END -->

JSDOC

https://github.com/jsdoc2md/jsdoc-to-markdown