1 | # markdown-it
|
2 |
|
3 | [![Build Status](https://img.shields.io/travis/markdown-it/markdown-it/master.svg?style=flat)](https://travis-ci.org/markdown-it/markdown-it)
|
4 | [![NPM version](https://img.shields.io/npm/v/markdown-it.svg?style=flat)](https://www.npmjs.org/package/markdown-it)
|
5 | [![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)
|
6 | [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/markdown-it/markdown-it)
|
7 |
|
8 | > Markdown parser done right. Fast and easy to extend.
|
9 |
|
10 | __[Live demo](https://markdown-it.github.io)__
|
11 |
|
12 | - Follows the __[CommonMark spec](http://spec.commonmark.org/)__ + adds syntax extensions & sugar (URL autolinking, typographer).
|
13 | - Configurable syntax! You can add new rules and even replace existing ones.
|
14 | - High speed.
|
15 | - [Safe](https://github.com/markdown-it/markdown-it/tree/master/docs/security.md) by default.
|
16 | - 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.
|
17 |
|
18 | __Table of content__
|
19 |
|
20 | - [Install](#install)
|
21 | - [Usage examples](#usage-examples)
|
22 | - [API](#api)
|
23 | - [Syntax extensions](#syntax-extensions)
|
24 | - [Benchmark](#benchmark)
|
25 | - [Authors](#authors)
|
26 | - [References / Thanks](#references--thanks)
|
27 | - [License](#license)
|
28 |
|
29 | ## Install
|
30 |
|
31 | **node.js** & **bower**:
|
32 |
|
33 | ```bash
|
34 | npm install markdown-it --save
|
35 | bower install markdown-it --save
|
36 | ```
|
37 |
|
38 | **browser (CDN):**
|
39 |
|
40 | - [jsDeliver CDN](http://www.jsdelivr.com/#!markdown-it "jsDelivr CDN")
|
41 | - [cdnjs.com CDN](https://cdnjs.com/libraries/markdown-it "cdnjs.com")
|
42 |
|
43 |
|
44 | ## Usage examples
|
45 |
|
46 | See also:
|
47 |
|
48 | - __[API documentation](https://markdown-it.github.io/markdown-it/)__ - for more
|
49 | info and examples.
|
50 | - [Development info](https://github.com/markdown-it/markdown-it/tree/master/docs) -
|
51 | for plugins writers.
|
52 |
|
53 |
|
54 | ### Simple
|
55 |
|
56 | ```js
|
57 | // node.js, "classic" way:
|
58 | var MarkdownIt = require('markdown-it'),
|
59 | md = new MarkdownIt();
|
60 | var result = md.render('# markdown-it rulezz!');
|
61 |
|
62 | // node.js, the same, but with sugar:
|
63 | var md = require('markdown-it')();
|
64 | var result = md.render('# markdown-it rulezz!');
|
65 |
|
66 | // browser without AMD, added to "window" on script load
|
67 | // Note, there is no dash in "markdownit".
|
68 | var md = window.markdownit();
|
69 | var result = md.render('# markdown-it rulezz!');
|
70 | ```
|
71 |
|
72 | Single line rendering, without paragraph wrap:
|
73 |
|
74 | ```js
|
75 | var md = require('markdown-it')();
|
76 | var result = md.renderInline('__markdown-it__ rulezz!');
|
77 | ```
|
78 |
|
79 |
|
80 | ### Init with presets and options
|
81 |
|
82 | (*) presets define combinations of active rules and options. Can be
|
83 | `"commonmark"`, `"zero"` or `"default"` (if skipped). See
|
84 | [API docs](https://markdown-it.github.io/markdown-it/#MarkdownIt.new) for more details.
|
85 |
|
86 | ```js
|
87 | // commonmark mode
|
88 | var md = require('markdown-it')('commonmark');
|
89 |
|
90 | // default mode
|
91 | var md = require('markdown-it')();
|
92 |
|
93 | // enable everything
|
94 | var md = require('markdown-it')({
|
95 | html: true,
|
96 | linkify: true,
|
97 | typographer: true
|
98 | });
|
99 |
|
100 | // full options list (defaults)
|
101 | var md = require('markdown-it')({
|
102 | html: false, // Enable HTML tags in source
|
103 | xhtmlOut: false, // Use '/' to close single tags (<br />).
|
104 | // This is only for full CommonMark compatibility.
|
105 | breaks: false, // Convert '\n' in paragraphs into <br>
|
106 | langPrefix: 'language-', // CSS language prefix for fenced blocks. Can be
|
107 | // useful for external highlighters.
|
108 | linkify: false, // Autoconvert URL-like text to links
|
109 |
|
110 | // Enable some language-neutral replacement + quotes beautification
|
111 | typographer: false,
|
112 |
|
113 | // Double + single quotes replacement pairs, when typographer enabled,
|
114 | // and smartquotes on. Could be either a String or an Array.
|
115 | //
|
116 | // For example, you can use '«»„“' for Russian, '„“‚‘' for German,
|
117 | // and ['«\xA0', '\xA0»', '‹\xA0', '\xA0›'] for French (including nbsp).
|
118 | quotes: '“”‘’',
|
119 |
|
120 | // Highlighter function. Should return escaped HTML,
|
121 | // or '' if the source string is not changed and should be escaped externaly.
|
122 | // If result starts with <pre... internal wrapper is skipped.
|
123 | highlight: function (/*str, lang*/) { return ''; }
|
124 | });
|
125 | ```
|
126 |
|
127 | ### Plugins load
|
128 |
|
129 | ```js
|
130 | var md = require('markdown-it')()
|
131 | .use(plugin1)
|
132 | .use(plugin2, opts, ...)
|
133 | .use(plugin3);
|
134 | ```
|
135 |
|
136 |
|
137 | ### Syntax highlighting
|
138 |
|
139 | Apply syntax highlighting to fenced code blocks with the `highlight` option:
|
140 |
|
141 | ```js
|
142 | var hljs = require('highlight.js'); // https://highlightjs.org/
|
143 |
|
144 | // Actual default values
|
145 | var md = require('markdown-it')({
|
146 | highlight: function (str, lang) {
|
147 | if (lang && hljs.getLanguage(lang)) {
|
148 | try {
|
149 | return hljs.highlight(lang, str).value;
|
150 | } catch (__) {}
|
151 | }
|
152 |
|
153 | return ''; // use external default escaping
|
154 | }
|
155 | });
|
156 | ```
|
157 |
|
158 | Or with full wrapper override (if you need assign class to `<pre>`):
|
159 |
|
160 | ```js
|
161 | var hljs = require('highlight.js'); // https://highlightjs.org/
|
162 |
|
163 | // Actual default values
|
164 | var md = require('markdown-it')({
|
165 | highlight: function (str, lang) {
|
166 | if (lang && hljs.getLanguage(lang)) {
|
167 | try {
|
168 | return '<pre class="hljs"><code>' +
|
169 | hljs.highlight(lang, str, true).value +
|
170 | '</code></pre>';
|
171 | } catch (__) {}
|
172 | }
|
173 |
|
174 | return '<pre class="hljs"><code>' + md.utils.escapeHtml(str) + '</code></pre>';
|
175 | }
|
176 | });
|
177 | ```
|
178 |
|
179 | ### Linkify
|
180 |
|
181 | `linkify: true` uses [linkify-it](https://github.com/markdown-it/linkify-it). To
|
182 | configure linkify-it, access the linkify instance through `md.linkify`:
|
183 |
|
184 | ```js
|
185 | md.linkify.tlds('.py', false); // disables .py as top level domain
|
186 | ```
|
187 |
|
188 |
|
189 | ## API
|
190 |
|
191 | __[API documentation](https://markdown-it.github.io/markdown-it/)__
|
192 |
|
193 | If you are going to write plugins - take a look at
|
194 | [Development info](https://github.com/markdown-it/markdown-it/tree/master/docs).
|
195 |
|
196 |
|
197 | ## Syntax extensions
|
198 |
|
199 | Embedded (enabled by default):
|
200 |
|
201 | - [Tables](https://help.github.com/articles/github-flavored-markdown/#tables) (GFM)
|
202 | - [Strikethrough](https://help.github.com/articles/github-flavored-markdown/#strikethrough) (GFM)
|
203 |
|
204 | Via plugins:
|
205 |
|
206 | - [subscript](https://github.com/markdown-it/markdown-it-sub)
|
207 | - [superscript](https://github.com/markdown-it/markdown-it-sup)
|
208 | - [footnote](https://github.com/markdown-it/markdown-it-footnote)
|
209 | - [definition list](https://github.com/markdown-it/markdown-it-deflist)
|
210 | - [abbreviation](https://github.com/markdown-it/markdown-it-abbr)
|
211 | - [emoji](https://github.com/markdown-it/markdown-it-emoji)
|
212 | - [custom container](https://github.com/markdown-it/markdown-it-container)
|
213 | - [insert](https://github.com/markdown-it/markdown-it-ins)
|
214 | - [mark](https://github.com/markdown-it/markdown-it-mark)
|
215 | - ... and [others](https://www.npmjs.org/browse/keyword/markdown-it-plugin)
|
216 |
|
217 |
|
218 | ### Manage rules
|
219 |
|
220 | By default all rules are enabled, but can be restricted by options. On plugin
|
221 | load all its rules are enabled automatically.
|
222 |
|
223 | ```js
|
224 | // Activate/deactivate rules, with curring
|
225 | var md = require('markdown-it')()
|
226 | .disable([ 'link', 'image' ])
|
227 | .enable([ 'link' ])
|
228 | .enable('image');
|
229 |
|
230 | // Enable everything
|
231 | md = require('markdown-it')({
|
232 | html: true,
|
233 | linkify: true,
|
234 | typographer: true,
|
235 | });
|
236 | ```
|
237 |
|
238 |
|
239 | ## Benchmark
|
240 |
|
241 | Here is the result of readme parse at MB Pro Retina 2013 (2.4 GHz):
|
242 |
|
243 | ```bash
|
244 | make benchmark-deps
|
245 | benchmark/benchmark.js readme
|
246 |
|
247 | Selected samples: (1 of 28)
|
248 | > README
|
249 |
|
250 | Sample: README.md (7774 bytes)
|
251 | > commonmark-reference x 1,222 ops/sec ±0.96% (97 runs sampled)
|
252 | > current x 743 ops/sec ±0.84% (97 runs sampled)
|
253 | > current-commonmark x 1,568 ops/sec ±0.84% (98 runs sampled)
|
254 | > marked x 1,587 ops/sec ±4.31% (93 runs sampled)
|
255 | ```
|
256 |
|
257 | __Note.__ CommonMark version runs with [simplified link normalizers](https://github.com/markdown-it/markdown-it/blob/master/benchmark/implementations/current-commonmark/index.js)
|
258 | for more "honest" compare. Difference is ~ 1.5x.
|
259 |
|
260 | As you can see, `markdown-it` doesn't pay with speed for it's flexibility.
|
261 | Slowdown of "full" version caused by additional features not available in
|
262 | other implementations.
|
263 |
|
264 |
|
265 | ## Authors
|
266 |
|
267 | - Alex Kocharin [github/rlidwka](https://github.com/rlidwka)
|
268 | - Vitaly Puzrin [github/puzrin](https://github.com/puzrin)
|
269 |
|
270 | _markdown-it_ is the result of the decision of the authors who contributed to
|
271 | 99% of the _Remarkable_ code to move to a project with the same authorship but
|
272 | new leadership (Vitaly and Alex). It's not a fork.
|
273 |
|
274 | ## References / Thanks
|
275 |
|
276 | Big thanks to [John MacFarlane](https://github.com/jgm) for his work on the
|
277 | CommonMark spec and reference implementations. His work saved us a lot of time
|
278 | during this project's development.
|
279 |
|
280 | **Related Links:**
|
281 |
|
282 | - https://github.com/jgm/CommonMark - reference CommonMark implementations in C & JS,
|
283 | also contains latest spec & online demo.
|
284 | - http://talk.commonmark.org - CommonMark forum, good place to collaborate
|
285 | developers' efforts.
|
286 |
|
287 | **Ports**
|
288 |
|
289 | - [motion-markdown-it](https://github.com/digitalmoksha/motion-markdown-it) - Ruby/RubyMotion
|
290 |
|
291 |
|
292 | ## License
|
293 |
|
294 | [MIT](https://github.com/markdown-it/markdown-it/blob/master/LICENSE)
|