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

Given any code with Markdown embedded in /** comments */:

/**
 * ## API
 * This is the API. (...)
 */

function api() { ... }

Use it to extract comments into a doc:

$ mdextract file.js > docs.md

Voila!

$ cat docs.md

## API
This is the API. (...)

$

Examples

• index.js from mdextract (output)
• read-input.js from read-input (output)
• navstack.js from Navstack (output)

Update mode

You can put <!-- include: ___ --> markers in a document:

$ cat README.md

  add `include` comments to your markdown file

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

And use mdextract --update to update the file, pulling Markdown from other files:

$ mdextract --update README.md

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

File format

Two stars: Any code block that begins with two stars ** will be treated as Markdown text.

/**
 * hello
 */

Sections: mark them with comments beginning with two stars, then have the first line end in a colon.

/**
 * 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, first line ends in a colon.

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

Code blocks: Markdown code blocks 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";

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