Showdown Options
Options can be set:
Setting a "global" option affects all instances of showdown
showdown.setOption('optionKey', 'value');Setting a "local" option only affects the specified Converter object. Local options can be set:
-
through the constructor
var converter = new showdown.Converter({optionKey: 'value'}); // example of multiple options var converter = new showdown.Converter({tables: true, strikethrough: true});
-
through the setOption() method
var converter = new showdown.Converter(); converter.setOption('optionKey', 'value');
Showdown provides 2 methods (both local and global) to retrieve previous set options.
// Global
var myOption = showdown.getOption('optionKey');
//Local
var myOption = converter.getOption('optionKey');// Global
var showdownGlobalOptions = showdown.getOptions();
//Local
var thisConverterSpecificOptions = converter.getOptions();You can get showdown's default options with:
var defaultOptions = showdown.getDefaultOptions();Please note that until version 1.6.0, all of these options are DISABLED by default in the cli tool.
| type | default | since | description |
|---|---|---|---|
| boolean | false | 1.0.0 | Omit the trailing newline in a code block |
By default, showdown adds a newline before the closing tags in code blocks. By enabling this option, that newline is removed.
This option affects both indented and fenced (gfm style) code blocks.
input:
var foo = 'bar';omitExtraWLInCodeBlocks = false:
<code><pre>var foo = 'bar';
</pre></code>omitExtraWLInCodeBlocks = true:
<code><pre>var foo = 'bar';</pre></code>| type | default | since | description |
|---|---|---|---|
| boolean | false | 1.1.0 | Disable the automatic generation of header ids |
Showdown generates an id for headings automatically. This is useful for linking to a specific header. This behavior, however, can be disabled with this option.
input:
# This is a headernoHeaderId = false
<h1 id="thisisaheader">This is a header</h1>noHeaderId = true
<h1>This is a header</h1>NOTE: Setting to true overrides prefixHeaderId and ghCompatibleHeaderId options
| type | default | since | description |
|---|---|---|---|
| boolean | false | 1.5.5 | Generate header ids compatible with github style |
This changes the format of the generated header IDs: spaces are replaced with dashes and a bunch of non alphanumeric chars are removed.
input:
# This is a header with @#$%ghCompatibleHeaderId = false
<h1 id="thisisaheader">This is a header</h1>ghCompatibleHeaderId = true
<h1 id="this-is-a-header-with-">This is a header with @#$%</h1>| type | default | since | description |
|---|---|---|---|
| string | boolean | 1.0.0 | Add a prefix to the generated header ids |
Adds 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.
| type | default | since | description |
|---|---|---|---|
| integer | 1 | 1.1.0 | Set the header starting level |
Sets the level from which header tags should start
input:
# headerheaderLevelStart = 1
<h1>header</h1>headerLevelStart = 3
<h3>header</h3>| type | default | since | description |
|---|---|---|---|
| boolean | false | 1.1.0 | Enable support for setting image dimensions from within markdown syntax |
Enables support for setting image dimensions from within markdown syntax.
 simple, assumes units are in px
 sets the height to "auto"
 Image with width of 80% and height of 5em
| type | default | since | description |
|---|---|---|---|
| boolean | false | 1.2.0 | Enable automatic linking in plain text urls |
Turning this option on will enable automatic linking when the parser find plain text urls
input:
some text www.google.comsimplifiedAutoLink = false
<p>some text www.google.com</p>simplifiedAutoLink = true
<p>some text <a href="www.google.com">www.google.com</a></p>| type | default | since | description |
|---|---|---|---|
| boolean | false | 1.5.1 | Excludes trailing punctuation from autolinked urls |
Excludes the follow characters from links: . ! ? ( )
This option only applies to links generated by simplifiedAutoLink.
input:
check this link www.google.com.excludeTrailingPunctuationFromURLs = false
<p>check this link <a href="www.google.com">www.google.com.</a></p>excludeTrailingPunctuationFromURLs = true
<p>check this link <a href="www.google.com">www.google.com</a>.</p>| type | default | since | description |
|---|---|---|---|
| boolean | false | 1.2.0 | Treats underscores in middle of words as literal characters |
Underscores are magic characters in markdown (as they delimit words that should be emphasised).
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.
input:
some text with__underscores__in middleliteralMidWordUnderscores = false
<p>some text with<strong>underscores</strong>in middle</p>literalMidWordUnderscores = true
<p>some text with__underscores__in middle</p>| type | default | since | description |
|---|---|---|---|
| boolean | false | 1.2.0 | Enable support for strikethrough syntax |
Enables support for strikethrough (<del>)
syntax:
~~strikethrough~~<del>strikethrough</del>| type | default | since | description |
|---|---|---|---|
| boolean | false | 1.2.0 | Enable support for tables syntax |
Enables support for table syntax.
syntax:
| h1 | h2 | h3 |
|:------|:-------:|--------:|
| 100 | [a][1] | ![b][2] |
| *foo* | **bar** | ~~baz~~ || type | default | since | description |
|---|---|---|---|
| boolean | false | 1.2.0 | Enable automatic generation of table headers ids |
If enabled, generates automatic ids for table headers. Only applies if tables is enabled.
| type | default | since | description |
|---|---|---|---|
| boolean | true | 1.2.0 | Enable support for GFM code block style syntax (fenced codeblocks) |
syntax:
```
some code here
```
NOTE: ghCodeBlocks are enabled by default since version 0.3.1
| type | default | since | description |
|---|---|---|---|
| boolean | false | 1.2.0 | Enable support for GFM takslists |
Enables support for github style tasklists
syntax:
- [x] This task is done
- [ ] This is still pending| type | default | since | description |
|---|---|---|---|
| boolean | false | 1.6.0 | Enable support for github @mentions |
Enables support for github @mentions, which links to the github profile page of the username mentioned
input:
hello there @tivieghMentions = false
<p>hello there @tivie</p>ghMentions = true
<p>hello there <a href="https://www.github.com/tivie>@tivie</a></p>
| type | default | since | description |
|---|---|---|---|
| boolean | https://github.com/{u} |
1.6.2 | Set link @mentions should point to |
Changes the link generated by @mentions. {u} is replaced by the text of the mentions. Only applies if ghMentions is enabled.
input:
hello there @tivieghMentionsLink = https://github.com/{u}
<p>hello there <a href="https://www.github.com/tivie>@tivie</a></p>
ghMentionsLink = http://mysite.com/{u}/profile
<p>hello there <a href="//mysite.com/tivie/profile">@tivie</a></p>| type | default | since | description |
|---|---|---|---|
| boolean | false | 1.2.1 | Fix weird effects due to parsing incomplete input |
On some circumstances, in live preview editors, when a paragraph is followed by a list it can cause an awkward effect.
You can prevent this by enabling this option
| type | default | since | description |
|---|---|---|---|
| boolean | false | 1.4.2 | Fix indentation problems related to es6 template strings in the midst of indented code |
Tries to smartly fix indentation problems related to es6 template strings in the midst of indented code
| type | default | since | description |
|---|---|---|---|
| boolean | false | 1.5.0 | Disable the requirement of indenting sublists by 4 spaces for them to be nested |
Disables the requirement of indenting sublists by 4 spaces for them to be nested, effectively reverting to the old behavior where 2 or 3 spaces were enough.
input:
- one
- two
...
- one
- twodisableForced4SpacesIndentedSublists = false
<ul>
<li>one</li>
<li>two</li>
</ul>
<p>...</p>
<ul>
<li>one
<ul>
<li>two</li>
</ul>
</li>
</ul>disableForced4SpacesIndentedSublists = true
<ul>
<li>one
<ul>
<li>two</li>
</ul>
</li>
</ul>
<p>...</p>
<ul>
<li>one
<ul>
<li>two</li>
</ul>
</li>
</ul>| type | default | since | description |
|---|---|---|---|
| boolean | false | 1.5.1 | Parse line breaks as <br/> in paragraphs (like GitHub does) |
Every newline character inside paragraphs and spans is parsed as <br/>
input:
a line
wrapped in twosimpleLineBreaks = false
<p>a line
wrapped in two</p>simpleLineBreaks = true
<p>a line<br>
wrapped in two</p>| type | default | since | description |
|---|---|---|---|
| boolean | false | 1.5.3 | Require a spance between # and header text |
Makes adding a space between # and the header text mandatory.
input:
#headerrequireSpaceBeforeHeadingText = false
<h1 id="header">header</h1>simpleLineBreaks = true
<p>#header</p>| type | default | since | description |
|---|---|---|---|
| boolean | true | 1.6.1 | Enable e-mail address automatic obfuscation |
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)
NOTE: Prior to version 1.6.1, emails would always be obfuscated through dec and hex encoding.
input:
encodeEmails = false
<a href="mailto:[email protected]">[email protected]</a>encodeEmails = true
<a href="mailto:myself@example.com">myself@example.com</a>