1 | ![Showdown][sd-logo]
|
2 |
|
3 | [![Build Status: Linux](https://travis-ci.org/showdownjs/showdown.svg?branch=master)](https://travis-ci.org/showdownjs/showdown)
|
4 | [![Build Status: Windows](https://ci.appveyor.com/api/projects/status/github/showdownjs/showdown?branch=master&svg=true)](https://ci.appveyor.com/project/tivie/showdown/branch/master)
|
5 | [![npm version](https://badge.fury.io/js/showdown.svg)](http://badge.fury.io/js/showdown)
|
6 | [![Bower version](https://badge.fury.io/bo/showdown.svg)](http://badge.fury.io/bo/showdown)
|
7 | [![Join the chat at https://gitter.im/showdownjs/showdown](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/showdownjs/showdown?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
8 | [![Greenkeeper badge](https://badges.greenkeeper.io/showdownjs/showdown.svg)](https://greenkeeper.io/)
|
9 | [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.me/tiviesantos)
|
10 |
|
11 | ------
|
12 |
|
13 | Showdown is a Javascript Markdown to HTML converter, based on the original works by John Gruber.
|
14 | Showdown can be used client side (in the browser) or server side (with NodeJs).
|
15 |
|
16 | ## Live DEMO
|
17 |
|
18 | Check a live Demo here http://showdownjs.github.io/demo/
|
19 |
|
20 |
|
21 | ## Who uses Showdown (or a fork)
|
22 |
|
23 | - [GoogleCloudPlatform](https://github.com/GoogleCloudPlatform)
|
24 | - [Ghost](https://ghost.org/)
|
25 | - [Meteor](https://www.meteor.com/)
|
26 | - [Stackexchange](http://stackexchange.com/) - forked as [PageDown](https://code.google.com/p/pagedown/)
|
27 | - [docular](https://github.com/Vertafore/docular)
|
28 | - [and some others...](https://www.npmjs.com/browse/depended/showdown)
|
29 |
|
30 | ## Donate [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.me/tiviesantos)
|
31 |
|
32 | We're currently looking to improve showdown with automated tests in all browsers and a proper domain and webpage.
|
33 | [If you like our work, please donate!!](https://www.paypal.me/tiviesantos) Your contribution will be greatly appreciated.
|
34 |
|
35 | ## Installation
|
36 |
|
37 | ### Download tarball
|
38 |
|
39 | You can download the latest release tarball directly from [releases][releases]
|
40 |
|
41 | ### Bower
|
42 |
|
43 | bower install showdown
|
44 |
|
45 | ### npm (server-side)
|
46 |
|
47 | npm install showdown
|
48 |
|
49 | ### NuGet package
|
50 |
|
51 | PM> Install-Package showdownjs
|
52 |
|
53 | The NuGet Packages can be [found here](https://www.nuget.org/packages/showdownjs/).
|
54 |
|
55 | ### CDN
|
56 |
|
57 | You can also use one of several CDNs available:
|
58 |
|
59 | * github CDN
|
60 |
|
61 | https://cdn.rawgit.com/showdownjs/showdown/<version tag>/dist/showdown.min.js
|
62 |
|
63 | * cdnjs
|
64 |
|
65 | https://cdnjs.cloudflare.com/ajax/libs/showdown/<version tag>/showdown.min.js
|
66 |
|
67 |
|
68 | ## Browser Compatibility
|
69 |
|
70 | Showdown has been tested successfully with:
|
71 |
|
72 | * Firefox 1.5 and 2.0
|
73 | * Chrome 12.0
|
74 | * Internet Explorer 6 and 7
|
75 | * Safari 2.0.4
|
76 | * Opera 8.54 and 9.10
|
77 | * Netscape 8.1.2
|
78 | * Konqueror 3.5.4
|
79 |
|
80 | In theory, Showdown will work in any browser that supports ECMA 262 3rd Edition (JavaScript 1.5).
|
81 | The converter itself might even work in things that aren't web browsers, like Acrobat. No promises.
|
82 |
|
83 |
|
84 | ## Node compatibility
|
85 |
|
86 | Showdown has been tested with node 0.8 and 0.10. However, it should work with previous versions, such as node 0.6.
|
87 |
|
88 |
|
89 | ## Legacy version
|
90 |
|
91 | If you're looking for showdown v<1.0.0, you can find it in the [**legacy branch**][legacy-branch].
|
92 |
|
93 | ## Changelog
|
94 |
|
95 | You can check the full [changelog][changelog]
|
96 |
|
97 | ## Extended documentation
|
98 | Check our [wiki pages][wiki] for examples and a more in-depth documentation.
|
99 |
|
100 |
|
101 | ## Quick Example
|
102 |
|
103 | ### Node
|
104 |
|
105 | ```js
|
106 | var showdown = require('showdown'),
|
107 | converter = new showdown.Converter(),
|
108 | text = '#hello, markdown!',
|
109 | html = converter.makeHtml(text);
|
110 | ```
|
111 |
|
112 | ### Browser
|
113 |
|
114 | ```js
|
115 | var converter = new showdown.Converter(),
|
116 | text = '#hello, markdown!',
|
117 | html = converter.makeHtml(text);
|
118 | ```
|
119 |
|
120 | ### Output
|
121 |
|
122 | Both examples should output...
|
123 |
|
124 | <h1 id="hellomarkdown">hello, markdown!</h1>
|
125 |
|
126 | ## Options
|
127 |
|
128 | You can change some of showdown's default behavior through options.
|
129 |
|
130 | ### Setting options
|
131 |
|
132 | Options can be set:
|
133 |
|
134 | #### Globally
|
135 |
|
136 | Setting a "global" option affects all instances of showdown
|
137 |
|
138 | ```js
|
139 | showdown.setOption('optionKey', 'value');
|
140 | ```
|
141 |
|
142 | #### Locally
|
143 | Setting a "local" option only affects the specified Converter object.
|
144 | Local options can be set:
|
145 |
|
146 | * **through the constructor**
|
147 | ```js
|
148 | var converter = new showdown.Converter({optionKey: 'value'});
|
149 | ```
|
150 |
|
151 | * **through the setOption() method**
|
152 | ```js
|
153 | var converter = new showdown.Converter();
|
154 | converter.setOption('optionKey', 'value');
|
155 | ```
|
156 |
|
157 | ### Getting an option
|
158 |
|
159 | Showdown provides 2 methods (both local and global) to retrieve previous set options.
|
160 |
|
161 | #### getOption()
|
162 |
|
163 | ```js
|
164 | // Global
|
165 | var myOption = showdown.getOption('optionKey');
|
166 |
|
167 | //Local
|
168 | var myOption = converter.getOption('optionKey');
|
169 | ```
|
170 |
|
171 | #### getOptions()
|
172 |
|
173 | ```js
|
174 | // Global
|
175 | var showdownGlobalOptions = showdown.getOptions();
|
176 |
|
177 | //Local
|
178 | var thisConverterSpecificOptions = converter.getOptions();
|
179 | ```
|
180 |
|
181 | ### Retrieve the default options
|
182 |
|
183 | You can get showdown's default options with:
|
184 | ```js
|
185 | var defaultOptions = showdown.getDefaultOptions();
|
186 | ```
|
187 |
|
188 | ### Valid Options
|
189 |
|
190 | * **omitExtraWLInCodeBlocks**: (boolean) [default false] Omit the trailing newline in a code block. Ex:
|
191 |
|
192 | This:
|
193 | ```html
|
194 | <code><pre>var foo = 'bar';
|
195 | </pre></code>
|
196 | ```
|
197 | Becomes this:
|
198 | ```html
|
199 | <code><pre>var foo = 'bar';</pre></code>
|
200 | ```
|
201 |
|
202 | * **noHeaderId**: (boolean) [default false] Disable the automatic generation of header ids.
|
203 | Setting to true overrides **prefixHeaderId**
|
204 |
|
205 | * **customizedHeaderId**: (boolean) [default false] Use text in curly braces as header id. **(since v1.7.0)**
|
206 | Example:
|
207 | ```
|
208 | ## Sample header {real-id} will use real-id as id
|
209 | ```
|
210 |
|
211 | * **ghCompatibleHeaderId**: (boolean) [default false] Generate header ids compatible with github style
|
212 | (spaces are replaced with dashes and a bunch of non alphanumeric chars are removed) **(since v1.5.5)**
|
213 |
|
214 | * **prefixHeaderId**: (string/boolean) [default false] Add a prefix to the generated header ids.
|
215 | Passing a string will prefix that string to the header id. Setting to `true` will add a generic 'section' prefix.
|
216 |
|
217 | * **rawPrefixHeaderId**: (boolean) [default false] Setting this option to true will prevent showdown from modifying the prefix.
|
218 | This might result in malformed IDs (if, for instance, the " char is used in the prefix).
|
219 | Has no effect if prefixHeaderId is set to false. **(since v 1.7.3)**
|
220 |
|
221 | * **rawHeaderId**: (boolean) [default false] Remove only spaces, ' and " from generated header ids (including prefixes),
|
222 | replacing them with dashes (-). WARNING: This might result in malformed ids **(since v1.7.3)**
|
223 |
|
224 | * **parseImgDimensions**: (boolean) [default false] Enable support for setting image dimensions from within markdown syntax.
|
225 | Examples:
|
226 | ```
|
227 | ![foo](foo.jpg =100x80) simple, assumes units are in px
|
228 | ![bar](bar.jpg =100x*) sets the height to "auto"
|
229 | ![baz](baz.jpg =80%x5em) Image with width of 80% and height of 5em
|
230 | ```
|
231 |
|
232 | * **headerLevelStart**: (integer) [default 1] Set the header starting level. For instance, setting this to 3 means that
|
233 |
|
234 | ```md
|
235 | # foo
|
236 | ```
|
237 | will be parsed as
|
238 |
|
239 | ```html
|
240 | <h3>foo</h3>
|
241 | ```
|
242 |
|
243 | * **simplifiedAutoLink**: (boolean) [default false] Turning this option on will enable automatic linking to urls.
|
244 | This means that:
|
245 |
|
246 | ```md
|
247 | some text www.google.com
|
248 | ```
|
249 | will be parsed as
|
250 | ````
|
251 | <p>some text <a href="www.google.com">www.google.com</a>
|
252 | ```
|
253 |
|
254 | * **excludeTrailingPunctuationFromURLs**: (boolean) [default false] This option excludes trailing punctuation from autolinking urls.
|
255 | Punctuation excluded: `. ! ? ( )`. Only applies if **simplifiedAutoLink** option is set to `true`.
|
256 |
|
257 | ```md
|
258 | check this link www.google.com!
|
259 | ```
|
260 | will be parsed as
|
261 | ```html
|
262 | <p>check this link <a href="www.google.com">www.google.com</a>!</p>
|
263 | ```
|
264 |
|
265 | * **literalMidWordUnderscores**: (boolean) [default false] Turning this on will stop showdown from interpreting
|
266 | underscores in the middle of words as `<em>` and `<strong>` and instead treat them as literal underscores.
|
267 |
|
268 | Example:
|
269 |
|
270 | ```md
|
271 | some text with__underscores__in middle
|
272 | ```
|
273 | will be parsed as
|
274 | ```html
|
275 | <p>some text with__underscores__in middle</p>
|
276 | ```
|
277 |
|
278 | * **literalMidWordAsterisks**: (boolean) [default false] Turning this on will stop showdown from interpreting asterisks
|
279 | in the middle of words as `<em>` and `<strong>` and instead treat them as literal asterisks.
|
280 |
|
281 | Example:
|
282 |
|
283 | ```md
|
284 | some text with**underscores**in middle
|
285 | ```
|
286 | will be parsed as
|
287 | ```html
|
288 | <p>some text with**underscores**in middle</p>
|
289 | ```
|
290 |
|
291 | * **strikethrough**: (boolean) [default false] Enable support for strikethrough syntax.
|
292 | `~~strikethrough~~` as `<del>strikethrough</del>`
|
293 |
|
294 | * **tables**: (boolean) [default false] Enable support for tables syntax. Example:
|
295 |
|
296 | ```md
|
297 | | h1 | h2 | h3 |
|
298 | |:------|:-------:|--------:|
|
299 | | 100 | [a][1] | ![b][2] |
|
300 | | *foo* | **bar** | ~~baz~~ |
|
301 | ```
|
302 |
|
303 | See the wiki for more info
|
304 |
|
305 | * **tablesHeaderId**: (boolean) [default false] If enabled adds an id property to table headers tags.
|
306 |
|
307 | * **ghCodeBlocks**: (boolean) [default true] Enable support for GFM code block style.
|
308 |
|
309 | * **tasklists**:(boolean) [default false] Enable support for GFM takslists. Example:
|
310 |
|
311 | ```md
|
312 | - [x] This task is done
|
313 | - [ ] This is still pending
|
314 | ```
|
315 | * **smoothLivePreview**: (boolean) [default false] Prevents weird effects in live previews due to incomplete input
|
316 |
|
317 | * **smartIndentationFix**: (boolean) [default false] Tries to smartly fix indentation problems related to es6 template
|
318 | strings in the midst of indented code.
|
319 |
|
320 | * **disableForced4SpacesIndentedSublists**: (boolean) [default false] Disables the requirement of indenting sublists
|
321 | by 4 spaces for them to be nested, effectively reverting to the old behavior where 2 or 3 spaces were enough.
|
322 | **(since v1.5.0)**
|
323 |
|
324 | * **simpleLineBreaks**: (boolean) [default false] Parses line breaks as <br> like GitHub does, without
|
325 | needing 2 spaces at the end of the line **(since v1.5.1)**
|
326 |
|
327 | ```md
|
328 | a line
|
329 | wrapped in two
|
330 | ```
|
331 |
|
332 | turns into:
|
333 |
|
334 | ```html
|
335 | <p>a line<br>
|
336 | wrapped in two</p>
|
337 | ```
|
338 |
|
339 | * **requireSpaceBeforeHeadingText**: (boolean) [default false] Makes adding a space between `#` and the header text mandatory **(since v1.5.3)**
|
340 |
|
341 | * **ghMentions**: (boolean) [default false] Enables github @mentions, which link to the username mentioned **(since v1.6.0)**
|
342 |
|
343 | * **ghMentionsLink**: (string) [default `https://github.com/{u}`] Changes the link generated by @mentions.
|
344 | Showdown will replace `{u}` with the username. Only applies if ghMentions option is enabled.
|
345 | Example: `@tivie` with ghMentionsOption set to `//mysite.com/{u}/profile` will result in `<a href="//mysite.com/tivie/profile">@tivie</a>`
|
346 |
|
347 | * **encodeEmails**: (boolean) [default true] Enables e-mail addresses encoding through the use of Character Entities, transforming ASCII e-mail addresses into its equivalent decimal entities. (since v1.6.1)
|
348 |
|
349 | NOTE: Prior to version 1.6.1, emails would always be obfuscated through dec and hex encoding.
|
350 |
|
351 | * **openLinksInNewWindow**: (boolean) [default false] Open all links in new windows
|
352 | (by adding the attribute `target="_blank"` to `<a>` tags) **(since v1.7.0)**
|
353 |
|
354 | * **backslashEscapesHTMLTags**: (boolean) [default false] Support for HTML Tag escaping. ex: `\<div>foo\</div>` **(since v1.7.2)**
|
355 |
|
356 | **NOTE**: Please note that until **version 1.6.0**, all of these options are ***DISABLED*** by default in the cli tool.
|
357 |
|
358 | ## Flavors
|
359 |
|
360 | You can also use flavors or presets to set the correct options automatically, so that showdown behaves like popular markdown flavors.
|
361 |
|
362 | Currently, the following flavors are available:
|
363 |
|
364 | * original - original markdown flavor as in [John Gruber's spec](https://daringfireball.net/projects/markdown/)
|
365 | * vanilla - showdown base flavor (as from v1.3.1)
|
366 | * github - GFM (GitHub Flavored Markdown)
|
367 |
|
368 |
|
369 | ### Global
|
370 | ```javascript
|
371 | showdown.setFlavor('github');
|
372 | ```
|
373 |
|
374 | ### Instance
|
375 | ```javascript
|
376 | converter.setFlavor('github');
|
377 | ```
|
378 |
|
379 |
|
380 | ## CLI Tool
|
381 |
|
382 | Showdown also comes bundled with a Command Line Interface tool. You can check the [CLI wiki page][cli-wiki] for more info
|
383 |
|
384 | ## Integration with AngularJS
|
385 |
|
386 | ShowdownJS project also provides seamlessly integration with AngularJS via a "plugin".
|
387 | Please visit https://github.com/showdownjs/ngShowdown for more information.
|
388 |
|
389 | ## Integration with TypeScript
|
390 |
|
391 | If you're using TypeScript you maybe want to use the types from [DefinitelyTyped][definitely-typed]
|
392 |
|
393 | ## Integration with SystemJS/JSPM
|
394 |
|
395 | Integration with SystemJS can be obtained via the third party ["system-md" plugin](https://github.com/guybedford/system-md).
|
396 |
|
397 | ## XSS vulnerability
|
398 |
|
399 | Showdown doesn't sanitize the input. This is by design since markdown relies on it to allow certain features to be correctly parsed into HTML.
|
400 | This, however, means XSS injection is quite possible.
|
401 |
|
402 | Please refer to the wiki article [Markdown's XSS Vulnerability (and how to mitigate it)][xss-wiki]
|
403 | for more information.
|
404 |
|
405 | ## Extensions
|
406 |
|
407 | Showdown allows additional functionality to be loaded via extensions. (you can find a list of known showdown extensions [here][ext-wiki])
|
408 | You can also find a boilerplate, to create your own extensions in [this repository][boilerplate-repo]
|
409 |
|
410 | ### Client-side Extension Usage
|
411 |
|
412 | ```js
|
413 | <script src="showdown.js" />
|
414 | <script src="twitter-extension.js" />
|
415 |
|
416 | var converter = new showdown.Converter({ extensions: ['twitter'] });
|
417 | ```
|
418 |
|
419 | ### Server-side Extension Usage
|
420 |
|
421 | ```js
|
422 | var showdown = require('showdown'),
|
423 | myExtension = require('myExtension'),
|
424 | converter = new showdown.Converter({ extensions: ['myExtension'] });
|
425 | ```
|
426 |
|
427 | ## Tests
|
428 |
|
429 | A suite of tests is available which require node.js. Once node is installed, run the following command from
|
430 | the project root to install the dependencies:
|
431 |
|
432 | npm install
|
433 |
|
434 | Once installed the tests can be run from the project root using:
|
435 |
|
436 | npm test
|
437 |
|
438 | New test cases can easily be added. Create a markdown file (ending in `.md`) which contains the markdown to test.
|
439 | Create a `.html` file of the exact same name. It will automatically be tested when the tests are executed with `mocha`.
|
440 |
|
441 | ## Contributing
|
442 |
|
443 | If you wish to contribute please read the following quick guide.
|
444 |
|
445 | ### Want a Feature?
|
446 | You can request a new feature by submitting an issue. If you would like to implement a new feature feel free to issue a
|
447 | Pull Request.
|
448 |
|
449 |
|
450 | ### Pull requests (PRs)
|
451 | PRs are awesome. However, before you submit your pull request consider the following guidelines:
|
452 |
|
453 | - Search GitHub for an open or closed Pull Request that relates to your submission. You don't want to duplicate effort.
|
454 | - When issuing PRs that change code, make your changes in a new git branch based on master:
|
455 |
|
456 | ```bash
|
457 | git checkout -b my-fix-branch master
|
458 | ```
|
459 |
|
460 | - Documentation (i.e: README.md) changes can be made directly against master.
|
461 | - Run the full test suite before submitting and make sure all tests pass (obviously =P).
|
462 | - Try to follow our [**coding style rules**][coding-rules].
|
463 | Breaking them prevents the PR to pass the tests.
|
464 | - Refrain from fixing multiple issues in the same pull request. It's preferable to open multiple small PRs instead of one
|
465 | hard to review big one.
|
466 | - If the PR introduces a new feature or fixes an issue, please add the appropriate test case.
|
467 | - We use commit notes to generate the changelog. It's extremely helpful if your commit messages adhere to the
|
468 | [**AngularJS Git Commit Guidelines**][ng-commit-guide].
|
469 | - If we suggest changes then:
|
470 | - Make the required updates.
|
471 | - Re-run the Angular test suite to ensure tests are still passing.
|
472 | - Rebase your branch and force push to your GitHub repository (this will update your Pull Request):
|
473 |
|
474 | ```bash
|
475 | git rebase master -i
|
476 | git push origin my-fix-branch -f
|
477 | ```
|
478 | - After your pull request is merged, you can safely delete your branch.
|
479 |
|
480 | If you have time to contribute to this project, we feel obliged that you get credit for it.
|
481 | These rules enable us to review your PR faster and will give you appropriate credit in your GitHub profile.
|
482 | We thank you in advance for your contribution!
|
483 |
|
484 | ### Joining the team
|
485 | We're looking for members to help maintaining Showdown.
|
486 | Please see [this issue](https://github.com/showdownjs/showdown/issues/114) to express interest or comment on this note.
|
487 |
|
488 | ## Credits
|
489 | Full credit list at https://github.com/showdownjs/showdown/blob/master/CREDITS.md
|
490 |
|
491 | Showdown is powered by:<br/>
|
492 | [![webstorm](https://www.jetbrains.com/webstorm/documentation/docs/logo_webstorm.png)](https://www.jetbrains.com/webstorm/)
|
493 |
|
494 |
|
495 |
|
496 | [sd-logo]: https://raw.githubusercontent.com/showdownjs/logo/master/dist/logo.readme.png
|
497 | [legacy-branch]: https://github.com/showdownjs/showdown/tree/legacy
|
498 | [releases]: https://github.com/showdownjs/showdown/releases
|
499 | [changelog]: https://github.com/showdownjs/showdown/blob/master/CHANGELOG.md
|
500 | [wiki]: https://github.com/showdownjs/showdown/wiki
|
501 | [cli-wiki]: https://github.com/showdownjs/showdown/wiki/CLI-tool
|
502 | [definitely-typed]: https://github.com/borisyankov/DefinitelyTyped/tree/master/showdown
|
503 | [xss-wiki]: https://github.com/showdownjs/showdown/wiki/Markdown's-XSS-Vulnerability-(and-how-to-mitigate-it)
|
504 | [ext-wiki]: https://github.com/showdownjs/showdown/wiki/extensions
|
505 | [coding-rules]: https://github.com/showdownjs/code-style/blob/master/README.md
|
506 | [ng-commit-guide]: https://github.com/showdownjs/code-style/blob/master/README.md#commit-message-convention
|
507 | [boilerplate-repo]: https://github.com/showdownjs/extension-boilerplate
|
508 |
|
\ | No newline at end of file |