mdextract
v1.0.0
Published
Extracts `/** code comments */` from code files and turns them into markdown docs. Supports JavaScript-style comments (other languages to come).
Downloads
6,179
Readme
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