For more information, see http://commonmark.org.
To play with this library without installing it, see the live dingus at http://try.commonmark.org/.
You can install the library using
npm install commonmark
This package includes the commonmark library and a
For client-side use, you can do
make dist to produce
suitable for linking into a web page, or fetch the latest
bower install commonmark.
npm install # if needed to fetch dependencies make test
npm install benchmark showdown marked markdown-it make bench
To start an interactive dingus that you can use to try out the library:
Instead of converting Markdown directly to HTML, as most converters
commonmark.js parses Markdown to an AST (abstract syntax tree),
and then renders this AST as HTML. This opens up the possibility of
manipulating the AST between parsing and rendering. For example, one
could transform emphasis into ALL CAPS.
Here's a basic usage example:
var reader = ;var writer = ;var parsed = reader; // parsed is a 'Node' tree// transform parsed if you like...var result = writer; // result is a String
The constructors for
HtmlRenderer take an optional
var writer = sourcepos: true;
The following options are currently supported:
true, source position information for block-level elements will be rendered in the
data-sourceposattribute (for HTML) or the
sourceposattribute (for XML).
true, straight quotes will be made curly,
--will be changed to an en dash,
---will be changed to an em dash, and
...will be changed to ellipses.
true, raw HTML will not be passed through to HTML output (it will be replaced by comments), and potentially unsafe URLs in links and images (those beginning with
file:, and with a few exceptions
data:) will be replaced with empty strings.
softbreak: specify raw string to be used for a softbreak.
esc: specify a function to be used to escape strings.
For example, to make soft breaks render as hard breaks in HTML:
var writer = softbreak: "<br />";
To make them render as spaces:
var writer = softbreak: " ";
esc, pass it a function with two parameters:
the first is the string to be escaped, the second is a boolean
true if entities in the string to be escaped should
In addition to the
HtmlRenderer, there is an
will produce an XML representation of the AST:
var writer = sourcepos: true;
The parser returns a Node. The following public properties are defined (those marked "read-only" have only a getter, not a setter):
type(read-only): a String, one of
firstChild(read-only): a Node or null.
lastChild(read-only): a Node or null.
next(read-only): a Node or null.
prev(read-only): a Node or null.
parent(read-only): a Node or null.
sourcepos(read-only): an Array with the following form:
[[startline, startcolumn], [endline, endcolumn]].
trueif the Node can contain other Nodes as children.
literal: the literal String content of the node or null.
destination: link or image destination (String) or null.
title: link or image title (String) or null.
info: fenced code block info string (String) or null.
level: heading level (Number).
listType: a String, either
trueif list is tight.
listStart: a Number, the starting number of an ordered list.
listDelimiter: a String, either
.for an ordered list.
onExit: Strings, used only for
Nodes have the following public methods:
appendChild(child): Append a Node
childto the end of the Node's children.
prependChild(child): Prepend a Node
childto the beginning of the Node's children.
unlink(): Remove the Node from the tree, severing its links with siblings and parents, and closing up gaps as needed.
insertAfter(sibling): Insert a Node
siblingafter the Node.
insertBefore(sibling): Insert a Node
siblingbefore the Node.
walker(): Returns a NodeWalker that can be used to iterate through the Node tree rooted in the Node.
The NodeWalker returned by
walker() has two methods:
next(): Returns an object with properties
entering(a boolean, which is
truewhen we enter a Node from a parent or sibling, and
falsewhen we reenter it from a child). Returns
nullwhen we have finished walking the tree.
resumeAt(node, entering): Resets the iterator to resume at the specified node and setting for
entering. (Normally this isn't needed unless you do destructive updates to the Node tree.)
Here is an example of the use of a NodeWalker to iterate through
the tree, making transformations. This simple example converts
the contents of all
text nodes to ALL CAPS:
var walker = parsed;var event node;while event = walkernextnode = eventnode;if evententering && nodetype === 'text'nodeliteral = nodeliteral;
This more complex example converts emphasis to ALL CAPS:
var walker = parsed;var event node;var inEmph = false;while event = walkernextnode = eventnode;if nodetype === 'emph'if evententeringinEmph = true;elseinEmph = false;// add Emph node's children as siblingswhile nodefirstChildnode;// remove the empty Emph nodenodeelse if inEmph && nodetype === 'text'nodeliteral = nodeliteral;
Exercises for the reader: write a transform to
- De-linkify a document, transforming links to regular text.
- Remove all raw HTML (
- Run fenced code blocks marked with a language name through
a syntax highlighting library, replacing them with an
HtmlBlockcontaining the highlighted code.
- Print warnings to the console for images without image descriptions or titles.
The command line executable parses CommonMark input from the specified files, or from stdin if no files are specified, and renders the result to stdout as HTML. If multiple input files are specified, their contents are concatenated before parsing, with newlines between them.
commonmark inputfile.md > outputfile.html commonmark intro.md chapter1.md chapter2.md > book.html
commonmark --help to get a summary of options.
A note on security
The library does not attempt to sanitize link attributes or
raw HTML. If you use this library in applications that accept
untrusted user input, you should either enable the
(see above) or run the output through an HTML sanitizer to protect against
Performance is excellent, roughly on par with
marked. On a benchmark
converting an 11 MB Markdown file built by concatenating the Markdown
sources of all localizations of the first edition of
Pro Git by Scott
Chacon, the command-line tool,
commonmark is just a bit slower than
the C program
discount, roughly ten times faster than PHP Markdown,
a hundred times faster than Python Markdown, and more than
a thousand times faster than
To generate this table,
npm install showdown marked markdown-it benchmark make bench-detailed