Markdown parser, done right. 100% CommonMark support, extensions, syntax plugins & high speed https://markdown-it.github.io/

9.2 KiB

Raw Blame History

markdown-it

Markdown parser done right. Fast and easy to extend.

Live demo

Supports the CommonMark spec + syntax extensions + sugar (URL autolinking, typographer).
Configurable syntax! You can add new rules and even replace existing ones.
High speed!
Community written plugins and other packages on npm.

Table of content

Install
Usage
Benchmark
Authors
References / Thanks
License

Install

node.js & bower:

npm install markdown-it --save
bower install markdown-it --save

browser (CDN):

jsDeliver CDN

Usage

// node.js, "classic" way:
var MarkdownIt = require('markdown-it'),
    md = new MarkdownIt();
console.log(md.render('# markdown-it rulezz!'));

// node.js, the same, but with sugar:
var md = require('markdown-it')();
console.log(md.render('# markdown-it rulezz!'));

// browser without AMD, added to "window" on script load
// Note, there are no dash.
var md = window.markdownit();
console.log(md.render('# markdown-it rulezz!'));

Single lines rendering, without paragraph wrap:

var md = require('markdown-it')();
console.log(md.renderInline('__markdown-it__ rulezz!'));

Configuring

By default markdown-it is configured to be similar to GFM, but with HTML disabled. This is easy to change if you prefer different settings.

Usually, you will define everything via constructor.

constructor(preset, options)

preset (String) - "full"|"commonmark", optional.

markdown-it offers some presets as a convenience to quickly enable/disable active syntax rules and options for common use cases.

"commonmark" - enable strict CommonMark mode.
"full" - all rules enabled, but still without html, typographer & autolinker.
default - when no preset name given.
zero - all rules disabled (useful to quickly setup your config via .enable()).

// commonmark mode
var md = require('markdown-it')('commonmark');

// default mode
var md = require('markdown-it')();

// enable everything
var md = require('markdown-it')('full', {
  html: true,
  linkify: true,
  typographer: true
});

options

// Actual default values
var md = require('markdown-it')({
  html:         false,        // Enable HTML tags in source
  xhtmlOut:     false,        // Use '/' to close single tags (<br />).
                              // This is only for full CommonMark compatibility.
  breaks:       false,        // Convert '\n' in paragraphs into <br>
  langPrefix:   'language-',  // CSS language prefix for fenced blocks. Can be
                              // useful for external highlighters.
  linkify:      false,        // Autoconvert URL-like text to links

  // Enable some language-neutral replacement + quotes beautification
  typographer:  false,

  // Double + single quotes replacement pairs, when typographer enabled,
  // and smartquotes on. Set doubles to '«»' for Russian, '„“' for German.
  quotes: '“”‘’',

  // Highlighter function. Should return escaped HTML,
  // or '' if the source string is not changed and should be escaped externaly.
  highlight: function (/*str, lang*/) { return ''; }
});

.set({ keys: values })

Probably, you will never need it. But you can change options after constructor call.

var md = require('markdown-it')()
            .set({ html: true, breaks: true })
            .set({ typographer, true });

Note: To achieve the best possible performance, don't modify a markdown-it instance on the fly. If you need multiple configurations it's best to create multiple instances and initialize each with separate config.

.use(plugin, options)

Sugar to activate plugins.

var md = require('markdown-it')()
            .use(plugin1)
            .use(plugin2, opts)
            .use(plugin3);

Syntax highlighting

Apply syntax highlighting to fenced code blocks with the highlight option:

var hljs = require('highlight.js') // https://highlightjs.org/

// Actual default values
var md = require('markdown-it')({
  highlight: function (str, lang) {
    if (lang && hljs.getLanguage(lang)) {
      try {
        return hljs.highlight(lang, str).value;
      } catch (err) {}
    }

    try {
      return hljs.highlightAuto(str).value;
    } catch (err) {}

    return ''; // use external default escaping
  }
});

Typographer

Although full-weight typographical replacements are language specific, markdown-it provides coverage for the most common and universal use cases:

var md = require('markdown-it')({
  typographer: true,
  quotes: '“”‘’'
});

// Disable rules at all:
md.disable([ 'replacements', 'smartquotes' ]);

// Actual default replacements:
//
// '' → ‘’
// "" → “”. Set '«»' for Russian, '„“' for German, empty to disable
// (c) (C) → ©
// (tm) (TM) → ™
// (r) (R) → ®
// +- → ±
// (p) (P) -> §
// ... → … (also ?.... → ?.., !.... → !..)
// ???????? → ???, !!!!! → !!!, `,,` → `,`
// -- → &ndash;, --- → &mdash;
//

Of course, you can also add your own rules or replace the defaults with something more advanced or specific to your language.

Syntax extensions

Enabled by default:

Tables (GFM)
<del> (GFM strikethrough) - ~~deleted text~~

Disabled by default:

<sup> - 19^th^
<sub> - H~2~0
abbreviations
footnotes
<ins> - ++inserted text++ (experimental)
<mark> - ==marked text== (experimental)

* Experimental extensions can be changed later for something like Critic Markup, but you will still be able to use old-style rules via external plugins if you prefer.

Manage rules

// Activate/deactivate rules
var md = require('markdown-it')()
            .enable([ 'ins', 'mark' ])
            .disable([ 'table' ]);

// Enable everything
md = require('markdown-it')('full', {
  html: true,
  linkify: true,
  typographer: true,
});

// Manually enable rules, disabled by default:
var md = require('markdown-it')()
            .enable([
              /* core */
              'abbr',
              /* block */
              'footnote',
              'deflist',
              /* inline */
              'footnote_inline',
              'ins',
              'mark',
              'sub',
              'sup'
            ]);

Benchmark

Here is result of CommonMark spec parse at Core i5 2.4 GHz (i5-4258U):

$ benchmark/benchmark.js spec
Selected samples: (1 of 27)
 > spec

Sample: spec.txt (110610 bytes)
 > commonmark-reference x 40.42 ops/sec ±4.07% (51 runs sampled)
 > current x 74.99 ops/sec ±4.69% (67 runs sampled)
 > current-commonmark x 93.76 ops/sec ±1.23% (79 runs sampled)
 > marked-0.3.2 x 22.92 ops/sec ±0.79% (41 runs sampled)

As you can see, markdown-it doesn't pay with speed for it's flexibility. Because it's written in monomorphyc style and use JIT inline caches effectively.

Authors

Alex Kocharin github/rlidwka
Vitaly Puzrin github/puzrin

References / Thanks

Big thanks to John MacFarlane for his work on the CommonMark spec and reference implementations. His work saved us a lot of time during this project's development.

Related Links:

https://github.com/jgm/CommonMark - reference CommonMark implementations in C & JS, also contains latest spec & online demo.
http://talk.commonmark.org - CommonMark forum, good place to collaborate developers' efforts.

License

MIT

9.2 KiB Raw Blame History