![Showdown][sd-logo]
Showdown is a Javascript Markdown to HTML converter, based on the original works by John Gruber. It can be used client side (in the browser) or server side (with Node or io).
## Installation
### Download tarball
You can download the latest release tarball directly from [releases][releases]
### Bower
bower install showdown
### npm (server-side)
npm install showdown
### CDN
You can also use one of several CDNs available:
* rawgit CDN
https://cdn.rawgit.com/showdownjs/showdown//dist/showdown.min.js
* cdnjs
https://cdnjs.cloudflare.com/ajax/libs/showdown//showdown.min.js
[sd-logo]: https://raw.githubusercontent.com/showdownjs/logo/master/dist/logo.readme.png
[releases]: https://github.com/showdownjs/showdown/releases
[atx]: http://www.aaronsw.com/2002/atx/intro
[setext]: https://en.wikipedia.org/wiki/Setext
---------
## Syntax
This new ruleset is based on the comments of Markdown's author John Gruber in the [Markdown discussion list][md-newsletter].
## Introduction
Showdown was created by John Fraser as a direct port of the original parser written by markdown's creator, John Gruber. Although Showdown has evolved since its inception, in "vanilla mode", it tries to follow the [original markdown spec][md-spec] (henceforth refereed as vanilla) as much as possible. There are, however, a few important differences, mainly due to inconsistencies in the original spec, which we addressed following the author's advice as stated in the [markdown's "official" newsletter][md-newsletter].
Showdown also support "extra" syntax not defined in the original spec as opt-in features. This means new syntax elements are not enabled by default and require users to enable them through options.
This document provides a quick description the syntax supported and the differences in output from the original markdown.pl implementation.
## Paragraphs
Paragraphs in Showdown are just **one or more lines of consecutive text** followed by one or more blank lines.
```md
On July 2, an alien mothership entered Earth's orbit and deployed several dozen
saucer-shaped "destroyer" spacecraft, each 15 miles (24 km) wide.
On July 3, the Black Knights, a squadron of Marine Corps F/A-18 Hornets,
participated in an assault on a destroyer near the city of Los Angeles.
```
The implication of the “one or more consecutive lines of text” is that Showdown supports
“hard-wrapped” text paragraphs. This means the following examples produce the same output:
```md
A very long line of text
```
```md
A very
long line
of text
```
If you DO want to add soft line breaks (which translate to `
` in HTML) to a paragraph, you can do so by adding 3 space characters to the end of the line (` `). You can also force every line break in paragraphs to translate to `
` (as Github does) by enabling the option **`simpleLineBreaks`**. ## Headings ### Atx Style You can create a heading by adding one or more # symbols before your heading text. The number of # you use will determine the size of the heading. This is similar to [**atx style**][atx]. ```md # The largest heading (an tag)
## The second largest heading (an
bar
baz
` in HTML) to a paragraph, you can do so by adding 3 space characters to the end of the line (` `). You can also force every line break in paragraphs to translate to `
` (as Github does) by enabling the option **`simpleLineBreaks`**. ## Headings ### Atx Style You can create a heading by adding one or more # symbols before your heading text. The number of # you use will determine the size of the heading. This is similar to [**atx style**][atx]. ```md # The largest heading (an
tag)
## The second largest heading (an tag)
…
###### The 6th largest heading (an tag)
```
The space between `#` and the heading text is not required but you can make that space mandatory by enabling the option **`requireSpaceBeforeHeadingText`**.
You can wrap the headings in `#`. Both leading and trailing `#` will be removed.
```md
## My Heading ##
```
If, for some reason, you need to keep a leading or trailing `#`, you can either add a space or escape it:
```md
# # My header # #
#\# My Header \# #
```
### Setext style
You can also use [**setext style**][setext] headings, although only two levels are available.
```md
This is an H1
=============
This is an H2
-------------
```
**Note:**
In live preview editors, when a paragraph is followed by a list it can cause an awkward effect.
![awkward effect][]
You can prevent this by enabling the option **`smoothPreview`**.
### Header IDs
Showdown generates bookmarks anchors in titles automatically, by adding an id property to an heading.
```md
# My cool header with ID
```
```html
My cool header with ID
```
This behavior can be modified with options:
- **`noHeaderId`** disables automatic id generation;
- **`ghCompatibleHeaderId`** generates header ids compatible with github style (spaces are replaced with dashes and a bunch of non alphanumeric chars are removed)
- **`prefixHeaderId`** adds a prefix to the generated header ids (either automatic or custom).
- **`headerLevelStart`** sets the header starting level. For instance, setting this to 3 means that `# header` will be converted to ``.
Read the [README.md][readme] for more info
## Blockquotes
You can indicate blockquotes with a >.
```md
In the words of Abraham Lincoln:
> Pardon my french
```
Blockquotes can have multiple paragraphs and can have other block elements inside.
```md
> A paragraph of text
>
> Another paragraph
>
> - A list
> - with items
```
## Bold and Italic
You can make text bold or italic.
*This text will be italic*
**This text will be bold**
Both bold and italic can use either a \* or an \_ around the text for styling. This allows you to combine both bold and italic if needed.
**Everyone _must_ attend the meeting at 5 o'clock today.**
## Strikethrough
With the option **`strikethrough`** enabled, Showdown supports strikethrough elements.
The syntax is the same as GFM, that is, by adding two tilde (`~~`) characters around
a word or groups of words.
```md
a ~~strikethrough~~ element
```
a ~~strikethrough~~ element
## Emojis
Since version 1.8.0, showdown supports github's emojis. A complete list of available emojis can be foun [here][emoji list].
```md
this is a :smile: smile emoji
```
this is a :smile: smile emoji
## Code formatting
### Inline formats
Use single backticks (`) to format text in a special monospace format. Everything within the backticks appear as-is, with no other special formatting.
```md
Here's an idea: why don't we take `SuperiorProject` and turn it into `**Reasonable**Project`.
```
```html
tag)
```
The space between `#` and the heading text is not required but you can make that space mandatory by enabling the option **`requireSpaceBeforeHeadingText`**.
You can wrap the headings in `#`. Both leading and trailing `#` will be removed.
```md
## My Heading ##
```
If, for some reason, you need to keep a leading or trailing `#`, you can either add a space or escape it:
```md
# # My header # #
#\# My Header \# #
```
### Setext style
You can also use [**setext style**][setext] headings, although only two levels are available.
```md
This is an H1
=============
This is an H2
-------------
```
**Note:**
In live preview editors, when a paragraph is followed by a list it can cause an awkward effect.
![awkward effect][]
You can prevent this by enabling the option **`smoothPreview`**.
### Header IDs
Showdown generates bookmarks anchors in titles automatically, by adding an id property to an heading.
```md
# My cool header with ID
```
```html
My cool header with ID
```
This behavior can be modified with options:
- **`noHeaderId`** disables automatic id generation;
- **`ghCompatibleHeaderId`** generates header ids compatible with github style (spaces are replaced with dashes and a bunch of non alphanumeric chars are removed)
- **`prefixHeaderId`** adds a prefix to the generated header ids (either automatic or custom).
- **`headerLevelStart`** sets the header starting level. For instance, setting this to 3 means that `# header` will be converted to ``.
Read the [README.md][readme] for more info
## Blockquotes
You can indicate blockquotes with a >.
```md
In the words of Abraham Lincoln:
> Pardon my french
```
Blockquotes can have multiple paragraphs and can have other block elements inside.
```md
> A paragraph of text
>
> Another paragraph
>
> - A list
> - with items
```
## Bold and Italic
You can make text bold or italic.
*This text will be italic*
**This text will be bold**
Both bold and italic can use either a \* or an \_ around the text for styling. This allows you to combine both bold and italic if needed.
**Everyone _must_ attend the meeting at 5 o'clock today.**
## Strikethrough
With the option **`strikethrough`** enabled, Showdown supports strikethrough elements.
The syntax is the same as GFM, that is, by adding two tilde (`~~`) characters around
a word or groups of words.
```md
a ~~strikethrough~~ element
```
a ~~strikethrough~~ element
## Emojis
Since version 1.8.0, showdown supports github's emojis. A complete list of available emojis can be foun [here][emoji list].
```md
this is a :smile: smile emoji
```
this is a :smile: smile emoji
## Code formatting
### Inline formats
Use single backticks (`) to format text in a special monospace format. Everything within the backticks appear as-is, with no other special formatting.
```md
Here's an idea: why don't we take `SuperiorProject` and turn it into `**Reasonable**Project`.
```
```html
Here's an idea: why don't we take SuperiorProject
and turn it into **Reasonable**Project
.
` tags in the HTML output. So this input: ```md * Bird * Magic * Johnson ``` Results in: ```html
Bird
Magic
Johnson
hey @tivie, check this out
``` ## Handling HTML in markdown documents Showdown, in most cases, leaves HTML tags alone, leaving them untouched in the output document. ```md some markdown **here**this is *not* **parsed**
```
```html
some markdown here