8.9 KiB
markdown-it
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 other packages on npm.
Table of content
Install
node.js & bower:
npm install markdown-it --save
bower install markdown-it --save
browser (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!'));
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.
// 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 ?.... → ?.., !.... → !..)
// ???????? → ???, !!!!! → !!!, `,,` → `,`
// -- → –, --- → —
//
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:
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.