mdextract

Extracts /** code comments */ from code files and turns them into markdown docs. Supports JavaScript-style comments (other languages to come).

$ npm install -g mdextract
$ mdextract --help

Use it to extract comments into a doc:

$ mdextract file.js > docs.md

Or update a doc:

$ cat README.md

  add `include` comments to your markdown file

  <!-- include: file.js -->
  <!-- /include: file.js -->

$ mdextract --update README.md

...the --update mode is great for making Readme-based documentation in small projects. It is idempotent.

File format

Sections: mark them with comments beginning with two stars.

/**
 * Sections:
 * Start your sections with two stars.
 *
 * If your first line of text ends in a colon (:), it will be turned into an
 * `<h3>` heading.
 */

Main sections: three stars.

/***
 * Main sections:
 * If you start sections with three stars, the headings will be turned into
 * `<h2>` headings.
 */

Code blocks: They will be converted into syntax-highlighted code fences.

/**
 * An example:
 *
 *     function () {
 *       return true;
 *     }
 */

Definition lists: Use ~ as a bullet. Great for parameter lists.

/**
 * ~ name: description
 * ~ id: the identifier
 * ~ callback (Function): the callback to run afterwards
 */

Sample usage: Use name : usage as your first line to specify a sample usage.

/**
 * push : push(name, fn)
 * Adds an item to the stack.
 */

Single-line mode: for short documentations.

/** id: the identifier. */
this.id = null;

/** name: the name. */
this.name = "Hello";

Examples

• index.js from mdextract (output)
• navstack.js from Navstack (output)

Thanks

mdextract © 2014+, Rico Sta. Cruz. Released under the MIT License. Authored and maintained by Rico Sta. Cruz with help from contributors.

ricostacruz.com  ·  GitHub @rstacruz  ·  Twitter @rstacruz