Markdown parser done right. Fast and easy to extend.
- 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 utilities on npm.
Table of content
node.js & bower:
npm install markdown-it --save
bower install markdown-it --savebrowser (CDN):
// 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!'));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.
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.
// 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 ''; }
});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.
Sugar to activate plugins.
var md = require('markdown-it')()
.use(plugin1)
.use(plugin2, opts)
.use(plugin3);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
}
});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 ?.... → ?.., !.... → !..)
// ???????? → ???, !!!!! → !!!, `,,` → `,`
// -- → –, --- → —
//Of course, you can also add your own rules or replace the defaults with something more advanced or specific to your language.
Enabled by default:
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.
// 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'
]);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.
- Alex Kocharin github/rlidwka
- Vitaly Puzrin github/puzrin
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.