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