# markdown-it
[](https://travis-ci.org/markdown-it/markdown-it)
[](https://www.npmjs.org/package/markdown-it)
[](https://coveralls.io/r/markdown-it/markdown-it?branch=master)
[](https://gitter.im/markdown-it/markdown-it)
> Markdown parser done right. Fast and easy to extend.
__[Live demo](https://markdown-it.github.io)__
- Follows the __ [CommonMark spec ](http://spec.commonmark.org/ )__ + adds syntax extensions & sugar (URL autolinking, typographer).
- Configurable syntax! You can add new rules and even replace existing ones.
- High speed.
- [Safe ](https://github.com/markdown-it/markdown-it/tree/master/docs/security.md ) by default.
- Community-written __ [plugins ](https://www.npmjs.org/browse/keyword/markdown-it-plugin )__ and [other packages ](https://www.npmjs.org/browse/keyword/markdown-it ) on npm.
__Table of content__
- [Install ](#install )
- [Usage examples ](#usage-examples )
- [API ](#api )
- [Syntax extensions ](#syntax-extensions )
- [Benchmark ](#benchmark )
- [Authors ](#authors )
- [References / Thanks ](#references--thanks )
- [License ](#license )
## Install
**node.js** & **bower** :
```bash
npm install markdown-it --save
bower install markdown-it --save
```
**browser (CDN):**
- [jsDeliver CDN ](http://www.jsdelivr.com/#!markdown-it "jsDelivr CDN" )
- [cdnjs.com CDN ](https://cdnjs.com/libraries/markdown-it "cdnjs.com" )
## Usage examples
See also:
- __[API documentation](https://markdown-it.github.io/markdown-it/)__ - for more
info and examples.
- [Development info ](https://github.com/markdown-it/markdown-it/tree/master/docs ) -
for plugins writers.
### Simple
```js
// 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 is no dash in "markdownit".
var md = window.markdownit();
var result = md.render('# markdown-it rulezz!');
```
Single line rendering, without paragraph wrap:
```js
var md = require('markdown-it')();
var result = md.renderInline('__markdown-it__ rulezz!');
```
### Init with presets and options
(*) presets define combinations of active rules and options. Can be
`"commonmark"` , `"zero"` or `"default"` (if skipped). See
[API docs ](https://markdown-it.github.io/markdown-it/#MarkdownIt.new ) for more details.
```js
// 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. Could be either a String or an Array.
//
// For example, you can use '«»„“' for Russian, '„“‚‘' for German,
// and ['«\xA0', '\xA0»', '‹\xA0', '\xA0›'] for French (including nbsp).
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
```js
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:
```js
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
__[API documentation](https://markdown-it.github.io/markdown-it/)__
If you are going to write plugins - take a look at
[Development info ](https://github.com/markdown-it/markdown-it/tree/master/docs ).
## Syntax extensions
Embedded (enabled by default):
- [Tables ](https://help.github.com/articles/github-flavored-markdown/#tables ) (GFM)
- [Strikethrough ](https://help.github.com/articles/github-flavored-markdown/#strikethrough ) (GFM)
Via plugins:
- [subscript ](https://github.com/markdown-it/markdown-it-sub )
- [superscript ](https://github.com/markdown-it/markdown-it-sup )
- [footnote ](https://github.com/markdown-it/markdown-it-footnote )
- [definition list ](https://github.com/markdown-it/markdown-it-deflist )
- [abbreviation ](https://github.com/markdown-it/markdown-it-abbr )
- [emoji ](https://github.com/markdown-it/markdown-it-emoji )
- [custom container ](https://github.com/markdown-it/markdown-it-container )
- [insert ](https://github.com/markdown-it/markdown-it-ins )
- [mark ](https://github.com/markdown-it/markdown-it-mark )
- ... and [others ](https://www.npmjs.org/browse/keyword/markdown-it-plugin )
### Manage rules
By default all rules are enabled, but can be restricted by options. On plugin
load all its rules are enabled automatically.
```js
// 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 the result of readme parse at MB Pro Retina 2013 (2.4 GHz):
```bash
$ benchmark/benchmark.js readme
Selected samples: (1 of 28)
> README
Sample: README.md (7774 bytes)
> commonmark-reference x 1,222 ops/sec ±0.96% (97 runs sampled)
> current x 743 ops/sec ±0.84% (97 runs sampled)
> current-commonmark x 1,568 ops/sec ±0.84% (98 runs sampled)
> marked-0.3.2 x 1,587 ops/sec ±4.31% (93 runs sampled)
```
__Note.__ CommonMark version runs with [simplified link normalizers ](https://github.com/markdown-it/markdown-it/blob/master/benchmark/implementations/current-commonmark/index.js )
for more "honest" compare. Difference is ~ 1.5x.
As you can see, `markdown-it` doesn't pay with speed for it's flexibility.
Slowdown of "full" version caused by additional features not available in
other implementations.
## Authors
- Alex Kocharin [github/rlidwka ](https://github.com/rlidwka )
- Vitaly Puzrin [github/puzrin ](https://github.com/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 ](https://github.com/jgm ) 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.
**Ports**
- [motion-markdown-it ](https://github.com/digitalmoksha/motion-markdown-it ) - Ruby/RubyMotion
## License
[MIT ](https://github.com/markdown-it/markdown-it/blob/master/LICENSE )
