diff options
Diffstat (limited to 'node_modules/markdown-it/README.md')
| -rw-r--r-- | node_modules/markdown-it/README.md | 294 |
1 files changed, 294 insertions, 0 deletions
diff --git a/node_modules/markdown-it/README.md b/node_modules/markdown-it/README.md new file mode 100644 index 00000000..bce39309 --- /dev/null +++ b/node_modules/markdown-it/README.md @@ -0,0 +1,294 @@ +# markdown-it + +[](https://travis-ci.org/markdown-it/markdown-it) +[](https://www.npmjs.org/package/markdown-it) +[](https://coveralls.io/github/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 externally. + // If result starts with <pre... internal wrapper is skipped. + 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 (__) {} + } + + return ''; // use external default escaping + } +}); +``` + +Or with full wrapper override (if you need assign class to `<pre>`): + +```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 '<pre class="hljs"><code>' + + hljs.highlight(lang, str, true).value + + '</code></pre>'; + } catch (__) {} + } + + return '<pre class="hljs"><code>' + md.utils.escapeHtml(str) + '</code></pre>'; + } +}); +``` + +### Linkify + +`linkify: true` uses [linkify-it](https://github.com/markdown-it/linkify-it). To +configure linkify-it, access the linkify instance through `md.linkify`: + +```js +md.linkify.tlds('.py', false); // disables .py as top level domain +``` + + +## 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/organizing-information-with-tables/) (GFM) +- [Strikethrough](https://help.github.com/articles/basic-writing-and-formatting-syntax/#styling-text) (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')({ + html: true, + linkify: true, + typographer: true, +}); +``` + + +## Benchmark + +Here is the result of readme parse at MB Pro Retina 2013 (2.4 GHz): + +```bash +make benchmark-deps +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 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) |