illuminate
v1.0.2
Published
Extract Markdown-formatted comments from JavaScript source code to build READMEs and API documentation.
Downloads
12
Readme
illuminate
Illuminate is a simple tool to extract Markdown-formatted comments from JavaScript source code, which can then be used to build READMEs or API documentation.
Install
Install from npm:
npm install -g illuminate
Usage Examples
The illuminate(1) cli operates over stdio, extracting Markdown comments from a JavaScript source file:
# Generate README.md from source code comments
illuminate < myfile.js > README.md
# Convert Markdown comments to HTML
$ illuminate --html < myfile.js > myfile.html
# Generate as .json to render with mustache(1)
$ illuminate --json --html < myfile.js | mustache - template.mustache
Usage
Programmatic Usage
illuminate can also be used programmatically as a node/io module. This might be convenient if you want to completely control Markdown processing.
Syntax
illuminate(source[, options])
Example
var readFileSync = require('fs').readFileSync;
var commonmark = require('commonmark');
var illuminate = require('illuminate');
var source = readFileSync(__dirname + '/myfile.js');
var api = illuminate(source);
var reader = new commonmark.Parser();
var writer = new commonmark.HtmlRenderer();
var parsed = reader.parse(api);
console.log(writer.render(parsed));
Options
html
: Convert Markdown to Use GitHub-flavored Markdown. Default istrue
.renderer
: Use a custom renderer for HTML output.gfm
: Use GitHub-flavored Markdown. Default istrue
.tables
: Enable GFM tables. Default istrue
.breaks
: Enable GFM line breaks. This option requires gfm to be enabled. Default istrue
.pedantic
: Conform to obscure parts of markdown.pl as much as possible. Default isfalse
.sanitize
:Sanitize the output. Ignore any HTML that has been input. Default isfalse
.smartLists
: Use smarter list behavior than the original markdown. Default isfalse
.smartypants
: Use "smart" typograhic punctuation for things like quotes and dashes. Default isfalse
.syntax
: Enable syntax highlighting using highlight.js during Markdown->HTML conversion. Default isfalse
.xhtml
: Render XHTML compatible output. Default isfalse
.
See Also
illuminate.Renderer
By default, illuminate uses a custom Renderer which inherits from marked.Renderer and generates unique IDs for headings.
You can override this renderer by setting options.renderer
, but if you'd
like to maintain the unique ID behavior, you can do something like:
var illuminate = require('illuminate');
var myRenderer = new illuminate.Renderer();
myRenderer.paragraph = function(text) {
// ...your custom rendering here...
return text;
};
See Also:
License
The MIT License (MIT)
Copyright © 2015 Benjamin Barber
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.