1 | # marked
|
2 |
|
3 | > A full-featured markdown parser and compiler, written in javascript. Built
|
4 | > for speed.
|
5 |
|
6 | [![NPM version](https://badge.fury.io/js/marked.png)][badge]
|
7 |
|
8 | ## Install
|
9 |
|
10 | ``` bash
|
11 | npm install marked --save
|
12 | ```
|
13 |
|
14 | ## Usage
|
15 |
|
16 | Minimal usage:
|
17 |
|
18 | ```js
|
19 | console.log(marked('I am using __markdown__.'));
|
20 | // Outputs: <p>I am using <i>markdown</i>.</p>
|
21 | ```
|
22 |
|
23 | Example using all options:
|
24 |
|
25 | ```js
|
26 | // Set default options except highlight which has no default
|
27 | marked.setOptions({
|
28 | gfm: true,
|
29 | highlight: function (code, lang, callback) {
|
30 | pygmentize({ lang: lang, format: 'html' }, code, function (err, result) {
|
31 | if (err) return callback(err);
|
32 | callback(null, result.toString());
|
33 | });
|
34 | },
|
35 | tables: true,
|
36 | breaks: false,
|
37 | pedantic: false,
|
38 | sanitize: true,
|
39 | smartLists: true,
|
40 | smartypants: false,
|
41 | langPrefix: 'lang-'
|
42 | });
|
43 |
|
44 | // Using async version of marked
|
45 | marked('I am using __markdown__.', function (err, content) {
|
46 | if (err) throw err;
|
47 | console.log(content);
|
48 | });
|
49 | ```
|
50 |
|
51 | ## marked(markdownString, [options], [callback])
|
52 |
|
53 | ### markdownString
|
54 |
|
55 | Type: `String`
|
56 |
|
57 | String of markdown source to be compiled.
|
58 |
|
59 | ### options
|
60 |
|
61 | Type: `Object`
|
62 |
|
63 | Hash of options. Can also be set using the `marked.setOptions` method as seen
|
64 | above.
|
65 |
|
66 | ### callback
|
67 |
|
68 | Type: `Function`
|
69 |
|
70 | Function called when the `markdownString` has been fully parsed when using
|
71 | async highlighting. If the `options` argument is omitted, this can be used as
|
72 | the second argument as seen above:
|
73 |
|
74 | ## Options
|
75 |
|
76 | ### gfm
|
77 |
|
78 | Type: `Boolean`
|
79 | Default: `true`
|
80 |
|
81 | Enable [GitHub flavored markdown][gfm].
|
82 |
|
83 | ### highlight
|
84 |
|
85 | Type: `Function`
|
86 |
|
87 | A function to highlight code blocks. The function takes three arguments: code,
|
88 | lang, and callback. The above example uses async highlighting with
|
89 | [node-pygementize-bundled][pygmentize], and here is a synchronous example using
|
90 | [highlight.js][highlight] which doesn't require the callback argument:
|
91 |
|
92 | ```js
|
93 | marked.setOptions({
|
94 | highlight: function (code, lang) {
|
95 | return hljs.highlightAuto(lang, code).value;
|
96 | }
|
97 | });
|
98 | ```
|
99 |
|
100 | #### highlight arguments
|
101 |
|
102 | `code`
|
103 |
|
104 | Type: `String`
|
105 |
|
106 | The section of code to pass to the highlighter.
|
107 |
|
108 | `lang`
|
109 |
|
110 | Type: `String`
|
111 |
|
112 | The programming language specified in the code block.
|
113 |
|
114 | `callback`
|
115 |
|
116 | Type: `String`
|
117 |
|
118 | The callback function to call when using an async highlighter.
|
119 |
|
120 | ### tables
|
121 |
|
122 | Type: `Boolean`
|
123 | Default: `true`
|
124 |
|
125 | Enable GFM [tables][tables].
|
126 | This option requires the `gfm` option to be true.
|
127 |
|
128 | ### breaks
|
129 |
|
130 | Type: `Boolean`
|
131 | Default: `false`
|
132 |
|
133 | Enable GFM [line breaks][breaks].
|
134 | This option requires the `gfm` option to be true.
|
135 |
|
136 | ### pedantic
|
137 |
|
138 | Type: `Boolean`
|
139 | Default: `false`
|
140 |
|
141 | Conform to obscure parts of `markdown.pl` as much as possible. Don't fix any of
|
142 | the original markdown bugs or poor behavior.
|
143 |
|
144 | ### sanitize
|
145 |
|
146 | Type: `Boolean`
|
147 | Default: `false`
|
148 |
|
149 | Sanitize the output. Ignore any HTML that has been input.
|
150 |
|
151 | ### smartLists
|
152 |
|
153 | Type: `Boolean`
|
154 | Default: `true`
|
155 |
|
156 | Use smarter list behavior than the original markdown. May eventually be
|
157 | default with the old behavior moved into `pedantic`.
|
158 |
|
159 | ### smartypants
|
160 |
|
161 | Type: `Boolean`
|
162 | Default: `false`
|
163 |
|
164 | Use "smart" typograhic punctuation for things like quotes and dashes.
|
165 |
|
166 | ### langPrefix
|
167 |
|
168 | Type: `String`
|
169 | Default: `lang-`
|
170 |
|
171 | Set the prefix for code block classes.
|
172 |
|
173 | ## Access to lexer and parser
|
174 |
|
175 | You also have direct access to the lexer and parser if you so desire.
|
176 |
|
177 | ``` js
|
178 | var tokens = marked.lexer(text, options);
|
179 | console.log(marked.parser(tokens));
|
180 | ```
|
181 |
|
182 | ``` js
|
183 | var lexer = new marked.Lexer(options);
|
184 | var tokens = lexer.lex(text);
|
185 | console.log(tokens);
|
186 | console.log(lexer.rules);
|
187 | ```
|
188 |
|
189 | ## CLI
|
190 |
|
191 | ``` bash
|
192 | $ marked -o hello.html
|
193 | hello world
|
194 | ^D
|
195 | $ cat hello.html
|
196 | <p>hello world</p>
|
197 | ```
|
198 |
|
199 | ## Benchmarks
|
200 |
|
201 | node v0.4.x
|
202 |
|
203 | ``` bash
|
204 | $ node test --bench
|
205 | marked completed in 12071ms.
|
206 | showdown (reuse converter) completed in 27387ms.
|
207 | showdown (new converter) completed in 75617ms.
|
208 | markdown-js completed in 70069ms.
|
209 | ```
|
210 |
|
211 | node v0.6.x
|
212 |
|
213 | ``` bash
|
214 | $ node test --bench
|
215 | marked completed in 6448ms.
|
216 | marked (gfm) completed in 7357ms.
|
217 | marked (pedantic) completed in 6092ms.
|
218 | discount completed in 7314ms.
|
219 | showdown (reuse converter) completed in 16018ms.
|
220 | showdown (new converter) completed in 18234ms.
|
221 | markdown-js completed in 24270ms.
|
222 | ```
|
223 |
|
224 | __Marked is now faster than Discount, which is written in C.__
|
225 |
|
226 | For those feeling skeptical: These benchmarks run the entire markdown test suite
|
227 | 1000 times. The test suite tests every feature. It doesn't cater to specific
|
228 | aspects.
|
229 |
|
230 | node v0.8.x
|
231 |
|
232 | ``` bash
|
233 | $ node test --bench
|
234 | marked completed in 3411ms.
|
235 | marked (gfm) completed in 3727ms.
|
236 | marked (pedantic) completed in 3201ms.
|
237 | robotskirt completed in 808ms.
|
238 | showdown (reuse converter) completed in 11954ms.
|
239 | showdown (new converter) completed in 17774ms.
|
240 | markdown-js completed in 17191ms.
|
241 | ```
|
242 |
|
243 | ## Another Javascript Markdown Parser
|
244 |
|
245 | The point of marked was to create a markdown compiler where it was possible to
|
246 | frequently parse huge chunks of markdown without having to worry about
|
247 | caching the compiled output somehow...or blocking for an unnecesarily long time.
|
248 |
|
249 | marked is very concise and still implements all markdown features. It is also
|
250 | now fully compatible with the client-side.
|
251 |
|
252 | marked more or less passes the official markdown test suite in its
|
253 | entirety. This is important because a surprising number of markdown compilers
|
254 | cannot pass more than a few tests. It was very difficult to get marked as
|
255 | compliant as it is. It could have cut corners in several areas for the sake
|
256 | of performance, but did not in order to be exactly what you expect in terms
|
257 | of a markdown rendering. In fact, this is why marked could be considered at a
|
258 | disadvantage in the benchmarks above.
|
259 |
|
260 | Along with implementing every markdown feature, marked also implements [GFM
|
261 | features][gfmf].
|
262 |
|
263 | ``` bash
|
264 | $ node
|
265 | > require('marked').lexer('> i am using marked.')
|
266 | [ { type: 'blockquote_start' },
|
267 | { type: 'paragraph',
|
268 | text: 'i am using marked.' },
|
269 | { type: 'blockquote_end' },
|
270 | links: {} ]
|
271 | ```
|
272 |
|
273 | ## Running Tests & Contributing
|
274 |
|
275 | If you want to submit a pull request, make sure your changes pass the test
|
276 | suite. If you're adding a new feature, be sure to add your own test.
|
277 |
|
278 | The marked test suite is set up slightly strangely: `test/new` is for all tests
|
279 | that are not part of the original markdown.pl test suite (this is where your
|
280 | test should go if you make one). `test/original` is only for the original
|
281 | markdown.pl tests. `test/tests` houses both types of tests after they have been
|
282 | combined and moved/generated by running `node test --fix` or `marked --test
|
283 | --fix`.
|
284 |
|
285 | In other words, if you have a test to add, add it to `test/new/` and then
|
286 | regenerate the tests with `node test --fix`. Commit the result. If your test
|
287 | uses a certain feature, for example, maybe it assumes GFM is *not* enabled, you
|
288 | can add `.nogfm` to the filename. So, `my-test.text` becomes
|
289 | `my-test.nogfm.text`. You can do this with any marked option. Say you want
|
290 | line breaks and smartypants enabled, your filename should be:
|
291 | `my-test.breaks.smartypants.text`.
|
292 |
|
293 | To run the tests:
|
294 |
|
295 | ``` bash
|
296 | cd marked/
|
297 | node test
|
298 | ```
|
299 |
|
300 | ### Contribution and License Agreement
|
301 |
|
302 | If you contribute code to marked, you are implicitly allowing your code to be
|
303 | distributed under the MIT license. You are also implicitly verifying that all
|
304 | code is your original work. `</legalese>`
|
305 |
|
306 | ## License
|
307 |
|
308 | Copyright (c) 2011-2013, Christopher Jeffrey. (MIT License)
|
309 |
|
310 | See LICENSE for more info.
|
311 |
|
312 | [gfm]: https://help.github.com/articles/github-flavored-markdown
|
313 | [gfmf]: http://github.github.com/github-flavored-markdown/
|
314 | [pygmentize]: https://github.com/rvagg/node-pygmentize-bundled
|
315 | [highlight]: https://github.com/isagalaev/highlight.js
|
316 | [badge]: http://badge.fury.io/js/marked
|
317 | [tables]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#wiki-tables
|
318 | [breaks]: https://help.github.com/articles/github-flavored-markdown#newlines
|