commonmark

What is commonmark?

The commonmark npm package is a JavaScript implementation of the CommonMark specification, which is a strongly defined, highly compatible specification of Markdown. It allows you to parse and render Markdown content in a consistent and predictable manner.

What are commonmark's main functionalities?

Parsing Markdown to AST

This feature allows you to parse Markdown text into an Abstract Syntax Tree (AST). The AST can then be manipulated or traversed for various purposes.

const commonmark = require('commonmark');
const reader = new commonmark.Parser();
const parsed = reader.parse('# Hello World');
console.log(parsed);

Rendering AST to HTML

This feature allows you to render the parsed AST back into HTML. This is useful for converting Markdown content into HTML for web pages.

const commonmark = require('commonmark');
const reader = new commonmark.Parser();
const writer = new commonmark.HtmlRenderer();
const parsed = reader.parse('# Hello World');
const result = writer.render(parsed);
console.log(result);

Customizing the Renderer

This feature allows you to customize the rendering process by extending the HtmlRenderer class. You can override methods to change how specific elements are rendered.

const commonmark = require('commonmark');
const reader = new commonmark.Parser();
class CustomRenderer extends commonmark.HtmlRenderer {
  // Override methods to customize rendering
  text(node) {
    this.lit('<span>' + node.literal + '</span>');
  }
}
const writer = new CustomRenderer();
const parsed = reader.parse('# Hello World');
const result = writer.render(parsed);
console.log(result);

Other packages similar to commonmark

marked

Marked is a fast, lightweight Markdown parser and compiler. It is designed to be simple to use and highly customizable. Compared to commonmark, marked is known for its speed and flexibility, but it may not adhere as strictly to the CommonMark specification.

markdown-it

Markdown-it is a Markdown parser that is both fast and extensible. It supports plugins and offers a high degree of customization. Unlike commonmark, markdown-it provides more features out of the box, such as syntax highlighting and support for custom containers.

remark

Remark is a Markdown processor powered by plugins. It can parse, transform, and compile Markdown. Remark is highly modular and allows for extensive customization through its plugin system. It offers more flexibility compared to commonmark but may require more setup.

README

commonmark.js

CommonMark is a rationalized version of Markdown syntax, with a spec and BSD3-licensed reference implementations in C and JavaScript.

For more information, see http://commonmark.org.

This repository contains the JavaScript reference implementation. It provides a library with functions for parsing CommonMark documents to an abstract syntax tree (AST), manipulating the AST, and rendering the document to HTML or to an XML representation of the AST.

To play with this library without installing it, see the live dingus at http://spec.commonmark.org/dingus.html.

Installing

You can install the library using npm:

npm install commonmark

This package includes the commonmark library and a command-line executable, commonmark.

For client-side use, you can do make dist to produce a standalone JavaScript file js/dist/commonmark.js, suitable for linking into a web page, or just fetch http://spec.commonmark.org/js/commonmark.js.

To run tests for the JavaScript library:

make test

To run benchmarks against some other JavaScript converters:

npm install benchmark showdown marked markdown-it
make bench

To start an interactive dingus that you can use to try out the library:

make dingus

Usage

Instead of converting Markdown directly to HTML, as most converters do, 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 = new commonmark.Parser();
var writer = new commonmark.HtmlRenderer();
var parsed = reader.parse("Hello *world*"); // parsed is a 'Node' tree
// transform parsed if you like...
var result = writer.render(parsed);  // result is a string

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 must run the output through an HTML sanitizer to protect against XSS attacks.

Performance

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 Markdown.pl.

Here are some focused benchmarks of four JavaScript libraries (using versions available on 24 Jan 2015). They test performance on different kinds of Markdown texts. (Most of these samples are taken from the markdown-it repository.) Results show a ratio of ops/second (higher is better) against the slowest implementation (always showdown).

Sample	showdown	commonmark	marked	markdown-it
README.md	1	3.3	3.1	4.3
block-bq-flat.md	1	9.3	13.6	13.7
block-bq-nested.md	1	12.5	10.6	13.2
block-code.md	1	28.8	64.7	95.4
block-fences.md	1	20.7	67.9	72.9
block-heading.md	1	11.1	11.8	19.6
block-hr.md	1	15.0	16.0	41.4
block-html.md	1	8.2	3.0	15.9
block-lheading.md	1	15.3	19.2	16.8
block-list-flat.md	1	4.6	4.4	10.7
block-list-nested.md	1	7.7	6.0	19.3
block-ref-flat.md	1	2.0	1.3	1.7
block-ref-nested.md	1	1.7	1.6	2.9
inline-autolink.md	1	4.4	7.4	4.7
inline-backticks.md	1	16.3	14.3	30.5
inline-em-flat.md	1	4.1	3.5	9.2
inline-em-nested.md	1	5.2	5.1	7.9
inline-em-worst.md	1	5.7	5.4	3.7
inline-entity.md	1	5.3	10.5	8.5
inline-escape.md	1	4.8	3.1	13.1
inline-html.md	1	3.6	5.4	5.1
inline-links-flat.md	1	3.5	4.2	4.1
inline-links-nested.md	1	4.1	1.1	1.6
inline-newlines.md	1	7.6	7.3	15.3
lorem1.md	1	8.9	5.1	5.7
rawtabs.md	1	9.7	10.6	15.4

To generate this table,

npm install showdown marked markdown-it benchmark
make bench-detailed

Authors

John MacFarlane wrote the first version of the JavaScript implementation. The block parsing algorithm was worked out together with David Greenspan. Kārlis Gaņģis helped work out a better parsing algorithm for links and emphasis, eliminating several worst-case performance issues. Vitaly Puzrin has offered much good advice about optimization and other issues.