![]() |
10 years ago | |
---|---|---|
.. | ||
README.md | 10 years ago | |
block-bq-flat.md | 10 years ago | |
block-bq-nested.md | 10 years ago | |
block-code.md | 10 years ago | |
block-fences.md | 10 years ago | |
block-heading.md | 10 years ago | |
block-hr.md | 10 years ago | |
block-html.md | 10 years ago | |
block-lheading.md | 10 years ago | |
block-list-flat.md | 10 years ago | |
block-list-nested.md | 10 years ago | |
block-ref-flat.md | 10 years ago | |
block-ref-list.md | 10 years ago | |
block-ref-nested.md | 10 years ago | |
block-tables.md | 10 years ago | |
inline-autolink.md | 10 years ago | |
inline-backticks.md | 10 years ago | |
inline-em-flat.md | 10 years ago | |
inline-em-nested.md | 10 years ago | |
inline-em-worst.md | 10 years ago | |
inline-entity.md | 10 years ago | |
inline-escape.md | 10 years ago | |
inline-html.md | 10 years ago | |
inline-links-flat.md | 10 years ago | |
inline-links-nested.md | 10 years ago | |
inline-newlines.md | 10 years ago | |
lorem1.txt | 10 years ago | |
rawtabs.md | 10 years ago |
README.md
markdown-it
Markdown parser done right. Fast and easy to extend.
v4.+ changed internals! Plugins need update. See migration details
- 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 examples
See also:
- API documentation - for more info and examples.
- Development info - for plugins writers.
Simple
// node.js, "classic" way:
var MarkdownIt = require('markdown-it'),
md = new MarkdownIt();
var result = md.render('# markdown-it rulezz!');
// node.js, the same, but with sugar:
var md = require('markdown-it')();
var result = md.render('# markdown-it rulezz!');
// browser without AMD, added to "window" on script load
// Note, there are no dash.
var md = window.markdownit();
var result = md.render('# markdown-it rulezz!');
Single line rendering, without paragraph wrap:
var md = require('markdown-it')();
var result = md.renderInline('__markdown-it__ rulezz!');
Init with presets and options
(*) preset define combination of active rules and options. Can be
"commonmark"
, "zero"
or "default"
(if skipped). See
API docs for more details.
// commonmark mode
var md = require('markdown-it')('commonmark');
// default mode
var md = require('markdown-it')();
// enable everything
var md = require('markdown-it')({
html: true,
linkify: true,
typographer: true
});
// full options list (defaults)
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 ''; }
});
Plugins load
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 (__) {}
}
try {
return hljs.highlightAuto(str).value;
} catch (__) {}
return ''; // use external default escaping
}
});
API
If you are going to write plugins - take a look at Development info.
Syntax extensions
Embedded (enabled by default):
- Tables (GFM)
- Strikethrough (GFM)
Via plugins:
- subscript
- superscript
- footnote
- definition list
- abbreviation
- emoji
- custom container
- insert
- mark
- ... and others
Manage rules
By default all rules are enabled, but can be restricted by options. On plugin load all it's rules are enabled automatically.
// Activate/deactivate rules, with curring
var md = require('markdown-it')()
.disable([ 'link', 'image' ])
.enable([ 'link' ])
.enable('image');
// Enable everything
md = require('markdown-it')('full', {
html: true,
linkify: true,
typographer: true,
});
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 68.63 ops/sec ±6.53% (72 runs sampled)
> current x 79.62 ops/sec ±3.22% (80 runs sampled)
> current-commonmark x 103 ops/sec ±1.10% (76 runs sampled)
> marked-0.3.2 x 23.14 ops/sec ±1.66% (42 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 uses JIT inline caches effectively.
Authors
- Alex Kocharin github/rlidwka
- Vitaly Puzrin github/puzrin
markdown-it is the result of the decision of the authors who contributed to 99% of the Remarkable code to move to a project with the same authorship but new leadership (Vitaly and Alex). It's not a fork.
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.