Markdown parser, done right. 100% CommonMark support, extensions, syntax plugins & high speed https://markdown-it.github.io/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

266 lines
8.1 KiB

# markdown-it
10 years ago
[![Build Status](https://img.shields.io/travis/markdown-it/markdown-it/master.svg?style=flat)](https://travis-ci.org/markdown-it/markdown-it)
10 years ago
[![NPM version](https://img.shields.io/npm/v/markdown-it.svg?style=flat)](https://www.npmjs.org/package/markdown-it)
10 years ago
[![Coverage Status](https://img.shields.io/coveralls/markdown-it/markdown-it/master.svg?style=flat)](https://coveralls.io/r/markdown-it/markdown-it?branch=master)
[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/markdown-it/markdown-it)
10 years ago
> Markdown parser done right. Fast and easy to extend.
10 years ago
__[Live demo](https://markdown-it.github.io)__
- Follows the __[CommonMark spec](http://spec.commonmark.org/)__ + adds syntax extensions & sugar (URL autolinking, typographer).
10 years ago
- 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.
10 years ago
__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)
10 years ago
## Install
10 years ago
**node.js** & **bower**:
10 years ago
```bash
npm install markdown-it --save
bower install markdown-it --save
10 years ago
```
**browser (CDN):**
- [jsDeliver CDN](http://www.jsdelivr.com/#!markdown-it "jsDelivr CDN")
10 years ago
- [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
10 years ago
```js
10 years ago
// 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
10 years ago
// 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
10 years ago
(*) presets define combinations of active rules and options. Can be
10 years ago
`"commonmark"`, `"zero"` or `"default"` (if skipped). See
[API docs](https://markdown-it.github.io/markdown-it/#MarkdownIt.new) for more details.
10 years ago
```js
// commonmark mode
10 years ago
var md = require('markdown-it')('commonmark');
// default mode
10 years ago
var md = require('markdown-it')();
// enable everything
10 years ago
var md = require('markdown-it')({
10 years ago
html: true,
linkify: true,
typographer: true
});
// full options list (defaults)
var md = require('markdown-it')({
html: false, // Enable HTML tags in source
10 years ago
xhtmlOut: false, // Use '/' to close single tags (<br />).
// This is only for full CommonMark compatibility.
breaks: false, // Convert '\n' in paragraphs into <br>
10 years ago
langPrefix: 'language-', // CSS language prefix for fenced blocks. Can be
// useful for external highlighters.
linkify: false, // Autoconvert URL-like text to links
10 years ago
// 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).
10 years ago
quotes: '“”‘’',
// Highlighter function. Should return escaped HTML,
10 years ago
// or '' if the source string is not changed and should be escaped externaly.
highlight: function (/*str, lang*/) { return ''; }
});
10 years ago
```
### Plugins load
10 years ago
```js
10 years ago
var md = require('markdown-it')()
.use(plugin1)
10 years ago
.use(plugin2, opts, ...)
10 years ago
.use(plugin3);
10 years ago
```
### Syntax highlighting
10 years ago
Apply syntax highlighting to fenced code blocks with the `highlight` option:
```js
10 years ago
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
}
});
```
10 years ago
## API
10 years ago
__[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
10 years ago
10 years ago
Embedded (enabled by default):
10 years ago
- [Tables](https://help.github.com/articles/github-flavored-markdown/#tables) (GFM)
10 years ago
- [Strikethrough](https://help.github.com/articles/github-flavored-markdown/#strikethrough) (GFM)
10 years ago
Via plugins:
10 years ago
- [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)
10 years ago
- [emoji](https://github.com/markdown-it/markdown-it-emoji)
- [custom container](https://github.com/markdown-it/markdown-it-container)
10 years ago
- [insert](https://github.com/markdown-it/markdown-it-ins)
- [mark](https://github.com/markdown-it/markdown-it-mark)
10 years ago
- ... and [others](https://www.npmjs.org/browse/keyword/markdown-it-plugin)
10 years ago
### Manage rules
10 years ago
By default all rules are enabled, but can be restricted by options. On plugin
10 years ago
load all its rules are enabled automatically.
10 years ago
10 years ago
```js
10 years ago
// Activate/deactivate rules, with curring
var md = require('markdown-it')()
10 years ago
.disable([ 'link', 'image' ])
.enable([ 'link' ])
.enable('image');
10 years ago
// Enable everything
md = require('markdown-it')('full', {
10 years ago
html: true,
linkify: true,
typographer: true,
});
10 years ago
```
## Benchmark
10 years ago
Here is the result of readme parse at MB Pro Retina 2013 (2.4 GHz):
```bash
10 years ago
$ 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)
```
10 years ago
__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.
10 years ago
Slowdown of "full" version caused by additional features not available in
10 years ago
other implementations.
10 years ago
## 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.
10 years ago
## 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.
10 years ago
**Ports**
- [motion-markdown-it](https://github.com/digitalmoksha/motion-markdown-it) - Ruby/RubyMotion
10 years ago
## License
[MIT](https://github.com/markdown-it/markdown-it/blob/master/LICENSE)