mdextract
Extracts `/** code comments */` from code files and turns them into markdown docs. Supports JavaScript-style comments (other languages to come).
Last updated 6 years ago by rstacruz .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install mdextract 
SYNC missed versions from official npm registry.

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

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

Current Tags

  • 1.0.0                                ...           latest (6 years ago)

2 Versions

  • 1.0.0                                ...           6 years ago
  • 0.1.0                                ...           6 years ago
Maintainers (1)
Downloads
Today 0
This Week 4
This Month 6
Last Day 4
Last Week 2
Last Month 12
Dependencies (1)
Dev Dependencies (4)

Copyright 2014 - 2016 © taobao.org |