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.

/* 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);

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

add-two-values

A module for adding two values.

add-two-values~add()

Add two values.

Kind: inner method of add-two-values

Options

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

defaults

Returns markdown documentation from jsdoc-annoted source code.

Kind: global constant

| Param | Type | Description | | --- | --- | --- | | files | Array.<object> | full path to the local javascript file that has the jsdoc comment | | heading-depth | number | The initial heading depth. For example, with a value of 2 the top-level markdown headings look like "## The heading". | | no-gfm | boolean | 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 | boolean | Put <hr> breaks between identifiers. Improves readability on bulky docs. | | module-index-format | string | none, grouped, table, dl. | | global-index-format | string | none, grouped, table, dl. | | param-list-format | string | 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 | string | list, table. | | member-index-format | string | grouped, list |

JSDOC

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