116 lines
3.8 KiB
Markdown
116 lines
3.8 KiB
Markdown
markdown-js
|
||
===========
|
||
|
||
Yet another markdown parser, this time for JavaScript. There's a few
|
||
options that precede this project but they all treat markdown to HTML
|
||
conversion as a single step process. You pass markdown in and get HTML
|
||
out, end of story. We had some pretty particular views on how the
|
||
process should actually look, which include:
|
||
|
||
* producing well-formed HTML. This means that em and strong nesting is
|
||
important, as is the ability to output as both HTML and XHTML
|
||
|
||
* having an intermediate representation to allow processing of parsed
|
||
data (we in fact have two, both [JsonML]: a markdown tree and an
|
||
HTML tree)
|
||
|
||
* being easily extensible to add new dialects without having to
|
||
rewrite the entire parsing mechanics
|
||
|
||
* having a good test suite. The only test suites we could find tested
|
||
massive blocks of input, and passing depended on outputting the HTML
|
||
with exactly the same whitespace as the original implementation
|
||
|
||
[JsonML]: http://jsonml.org/ "JSON Markup Language"
|
||
|
||
## Installation
|
||
|
||
Just the `markdown` library:
|
||
|
||
npm install markdown
|
||
|
||
Also install `md2html` to `/usr/local/bin` (or wherever)
|
||
|
||
npm install -g markdown
|
||
|
||
## Usage
|
||
|
||
The simple way to use it with CommonJS is:
|
||
|
||
var input = "# Heading\n\nParagraph";
|
||
var output = require( "markdown" ).markdown.toHTML( input );
|
||
print( output );
|
||
|
||
If you want more control check out the documentation in
|
||
[lib/markdown.js] which details all the methods and parameters
|
||
available (including examples!). One day we'll get the docs generated
|
||
and hosted somewhere for nicer browsing.
|
||
|
||
It also works in a browser; here is a complete example:
|
||
|
||
<!DOCTYPE html>
|
||
<html>
|
||
<body>
|
||
<textarea id="text-input" oninput="this.editor.update()"
|
||
rows="6" cols="60">Type **Markdown** here.</textarea>
|
||
<div id="preview"> </div>
|
||
<script src="lib/markdown.js"></script>
|
||
<script>
|
||
function Editor(input, preview)
|
||
{
|
||
this.update = function () {
|
||
preview.innerHTML = markdown.toHTML(input.value);
|
||
}
|
||
input.editor = this;
|
||
this.update();
|
||
}
|
||
var $ = function (id) { return document.getElementById(id); };
|
||
new Editor($("text-input"), $("preview"));
|
||
</script>
|
||
</body>
|
||
</html>
|
||
|
||
### md2html
|
||
|
||
md2html /path/to/doc.md > /path/to/doc.html
|
||
|
||
[lib/markdown.js]: http://github.com/evilstreak/markdown-js/blob/master/lib/markdown.js
|
||
|
||
## Intermediate Representation
|
||
|
||
Internally the process to convert a chunk of markdown into a chunk of
|
||
HTML has three steps:
|
||
|
||
1. Parse the markdown into a JsonML tree. Any references found in the
|
||
parsing are stored in the attribute hash of the root node under the
|
||
key `references`.
|
||
|
||
2. Convert the markdown tree into an HTML tree. Rename any nodes that
|
||
need it (`bulletlist` to `ul` for example) and lookup any references
|
||
used by links or images. Remove the references attribute once done.
|
||
|
||
3. Stringify the HTML tree being careful not to wreck whitespace where
|
||
whitespace is important (surrounding inline elements for example).
|
||
|
||
Each step of this process can be called individually if you need to do
|
||
some processing or modification of the data at an intermediate stage.
|
||
For example, you may want to grab a list of all URLs linked to in the
|
||
document before rendering it to HTML which you could do by recursing
|
||
through the HTML tree looking for `a` nodes.
|
||
|
||
## Running tests
|
||
|
||
To run the tests under node you will need tap installed (it's listed as a
|
||
devDependencies so `npm install` from the checkout should be enough), then do
|
||
|
||
$ ./node_modules/.bin/tap test/*.t.js
|
||
|
||
## Contributing
|
||
|
||
Do the usual github fork and pull request dance. Add yourself to the
|
||
contributors section of package.json too if you want to.
|
||
|
||
## License
|
||
|
||
Released under the MIT license.
|