Vitaly Puzrin
10 years ago
4 changed files with 276 additions and 6224 deletions
@ -0,0 +1,254 @@ |
|||
# 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)__ |
|||
|
|||
__v4.+ changed internals! Plugins need update. See [migration details](https://github.com/markdown-it/markdown-it/blob/master/docs/4.0_migration.md)__ |
|||
|
|||
- 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](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 are no dash. |
|||
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 |
|||
|
|||
(*) preset define combination 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. 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 |
|||
|
|||
```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 it's 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 result of CommonMark spec parse at Core i5 2.4 GHz (i5-4258U): |
|||
|
|||
```bash |
|||
$ 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](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. |
|||
|
|||
## License |
|||
|
|||
[MIT](https://github.com/markdown-it/markdown-it/blob/master/LICENSE) |
|||
File diff suppressed because it is too large
Loading…
Reference in new issue