# markdown-it [![Build Status](https://img.shields.io/travis/markdown-it/markdown-it/master.svg?style=flat)](https://travis-ci.org/markdown-it/markdown-it) [![NPM version](https://img.shields.io/npm/v/markdown-it.svg?style=flat)](https://www.npmjs.org/package/markdown-it) [![Coverage Status](https://coveralls.io/repos/markdown-it/markdown-it/badge.svg?branch=master&service=github)](https://coveralls.io/github/markdown-it/markdown-it?branch=master) [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](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 (
). // This is only for full CommonMark compatibility. breaks: false, // Convert '\n' in paragraphs into
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. // If result starts with `): ```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, true).value +
               '
'; } catch (__) {} } return '
' + md.utils.escapeHtml(str) + '
'; } }); ``` ### 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/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)