showdown
A bidirectional Markdown to HTML to Markdown converter written in Javascript
Top Related Projects
A markdown parser and compiler. Built for speed.
Markdown parser, done right. 100% CommonMark support, extensions, syntax plugins & high speed
CommonMark parser and renderer in JavaScript
Markdown parser, done right. Commonmark support, extensions, syntax plugins, high speed - all in one. Gulp and metalsmith plugins available. Used by Facebook, Docusaurus and many others! Use https://github.com/breakdance/breakdance for HTML-to-markdown conversion. Use https://github.com/jonschlinkert/markdown-toc to generate a table of contents.
A Markdown parser for javascript
Quick Overview
Showdown is a JavaScript library that allows you to convert Markdown to HTML. It's bidirectional, meaning it can also convert HTML back to Markdown. Showdown is flexible, extensible, and works both in the browser and on the server-side with Node.js.
Pros
- Easy to use and integrate into existing projects
- Supports a wide range of Markdown syntax, including GitHub Flavored Markdown
- Extensible through plugins and custom extensions
- Active development and community support
Cons
- Some advanced Markdown features may require additional configuration
- Performance can be slower compared to some other Markdown parsers
- Occasional inconsistencies in parsing complex nested structures
- Limited built-in sanitization options for user-generated content
Code Examples
- Basic Markdown to HTML conversion:
const converter = new showdown.Converter();
const markdown = '# Hello, Markdown!';
const html = converter.makeHtml(markdown);
console.log(html); // Outputs: <h1 id="hellomarkdown">Hello, Markdown!</h1>
- HTML to Markdown conversion:
const converter = new showdown.Converter();
const html = '<h1>Hello, HTML!</h1>';
const markdown = converter.makeMarkdown(html);
console.log(markdown); // Outputs: # Hello, HTML!
- Using options to customize behavior:
const converter = new showdown.Converter({
tables: true,
strikethrough: true,
tasklists: true
});
const markdown = '| Col1 | Col2 |\n|------|------|\n| A | B |\n\n~~strikethrough~~ \n\n- [x] Task 1\n- [ ] Task 2';
const html = converter.makeHtml(markdown);
console.log(html);
Getting Started
To use Showdown in your project, follow these steps:
-
Install Showdown via npm:
npm install showdown -
Import and use Showdown in your JavaScript file:
import showdown from 'showdown'; const converter = new showdown.Converter(); const markdown = '# Hello, Showdown!'; const html = converter.makeHtml(markdown); console.log(html); -
For browser usage, include Showdown via CDN:
<script src="https://cdnjs.cloudflare.com/ajax/libs/showdown/2.1.0/showdown.min.js"></script> <script> const converter = new showdown.Converter(); const markdown = '# Hello, Showdown!'; const html = converter.makeHtml(markdown); document.body.innerHTML = html; </script>
Competitor Comparisons
A markdown parser and compiler. Built for speed.
Pros of marked
- Faster parsing and rendering performance
- Smaller bundle size, making it more lightweight
- Stricter adherence to CommonMark specification
Cons of marked
- Less extensible, with fewer customization options
- Limited built-in features compared to Showdown
- Stricter parsing may not handle some non-standard Markdown syntax
Code Comparison
marked:
import { marked } from 'marked';
const html = marked.parse('# Heading\n\nParagraph');
Showdown:
import showdown from 'showdown';
const converter = new showdown.Converter();
const html = converter.makeHtml('# Heading\n\nParagraph');
Key Differences
- marked focuses on speed and strict compliance with CommonMark
- Showdown offers more flexibility and features out of the box
- marked has a simpler API, while Showdown provides more configuration options
- Showdown supports various flavors of Markdown, including GitHub Flavored Markdown
- marked is more suitable for projects prioritizing performance and standards compliance
- Showdown is better for applications requiring extensive customization or support for multiple Markdown variants
Both libraries are widely used and actively maintained, with the choice depending on specific project requirements and preferences.
Markdown parser, done right. 100% CommonMark support, extensions, syntax plugins & high speed
Pros of markdown-it
- Better performance and faster parsing speed
- More extensive plugin ecosystem and customization options
- Stricter CommonMark compliance
Cons of markdown-it
- Slightly steeper learning curve for advanced usage
- Less browser-friendly out of the box (primarily designed for Node.js)
Code Comparison
markdown-it:
const md = require('markdown-it')();
const result = md.render('# Hello, world!');
Showdown:
const showdown = require('showdown');
const converter = new showdown.Converter();
const result = converter.makeHtml('# Hello, world!');
Key Differences
- markdown-it focuses on extensibility and performance, making it ideal for server-side rendering and complex markdown processing tasks.
- Showdown is more straightforward to use and better suited for browser-based applications out of the box.
- markdown-it offers a more modular approach with its plugin system, allowing for fine-grained control over parsing and rendering.
- Showdown provides a simpler API and is often easier for beginners to get started with.
Both libraries are widely used and actively maintained, with markdown-it generally being favored for larger-scale or more complex projects, while Showdown is often chosen for simpler implementations or when browser compatibility is a primary concern.
CommonMark parser and renderer in JavaScript
Pros of commonmark.js
- Strictly adheres to the CommonMark specification, ensuring consistent and standardized Markdown parsing
- Faster parsing and rendering performance, especially for larger documents
- Provides a robust API for extending and customizing the parser
Cons of commonmark.js
- Less feature-rich compared to Showdown, with fewer built-in extensions
- Steeper learning curve for developers who want to extend or customize the parser
- Smaller community and ecosystem compared to Showdown
Code Comparison
commonmark.js:
var reader = new commonmark.Parser();
var writer = new commonmark.HtmlRenderer();
var parsed = reader.parse("Hello *world*");
var result = writer.render(parsed);
Showdown:
var converter = new showdown.Converter();
var result = converter.makeHtml("Hello *world*");
Summary
commonmark.js offers strict adherence to the CommonMark specification and better performance, making it ideal for projects requiring standardized Markdown parsing. However, it has fewer built-in features and a smaller ecosystem compared to Showdown. Showdown provides a simpler API and more extensions out of the box, but may not be as consistent in parsing across different implementations. The choice between the two depends on specific project requirements, such as parsing consistency, performance needs, and desired features.
Markdown parser, done right. Commonmark support, extensions, syntax plugins, high speed - all in one. Gulp and metalsmith plugins available. Used by Facebook, Docusaurus and many others! Use https://github.com/breakdance/breakdance for HTML-to-markdown conversion. Use https://github.com/jonschlinkert/markdown-toc to generate a table of contents.
Pros of Remarkable
- Faster parsing and rendering performance
- More extensive and customizable syntax support
- Smaller bundle size, beneficial for browser-based applications
Cons of Remarkable
- Less active development and maintenance
- Fewer built-in extensions compared to Showdown
- Steeper learning curve for advanced customizations
Code Comparison
Remarkable:
var md = new Remarkable();
var result = md.render('# Hello, *world*!');
Showdown:
var converter = new showdown.Converter();
var result = converter.makeHtml('# Hello, *world*!');
Both libraries offer similar basic usage, but Remarkable provides more options for configuration and customization:
var md = new Remarkable({
html: true,
breaks: true,
typographer: true
});
Showdown's configuration is typically done through extension loading:
showdown.setOption('optionKey', 'value');
converter.setOption('optionKey', 'value');
Overall, Remarkable offers better performance and more advanced features, while Showdown provides easier extensibility and more active community support. The choice between them depends on specific project requirements and preferences.
A Markdown parser for javascript
Pros of markdown-js
- Supports both CommonJS and AMD module systems
- Offers a more modular architecture, allowing for easier customization
- Provides a command-line interface for easy integration into build processes
Cons of markdown-js
- Less actively maintained, with fewer recent updates
- Smaller community and fewer contributors
- Limited built-in extensions compared to Showdown
Code Comparison
markdown-js:
var markdown = require( "markdown" ).markdown;
console.log(markdown.toHTML("Hello *World*!"));
Showdown:
var showdown = require('showdown'),
converter = new showdown.Converter();
console.log(converter.makeHtml('Hello *World*!'));
Additional Notes
Both Showdown and markdown-js are popular JavaScript libraries for converting Markdown to HTML. Showdown tends to have more frequent updates and a larger community, while markdown-js offers more flexibility in terms of module support and customization. The choice between the two depends on specific project requirements, such as the need for extensibility, active maintenance, or specific module system support.
Convert 
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
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 Node.js).
Live DEMO
Check out a live demo here: http://demo.showdownjs.com/
As you know, ShowdownJS is a free library and it will remain free forever. However, maintaining and improving the library costs time and money.
If you like our work and find our library useful, please donate through PayPal! Your contribution will be greatly appreciated and help me continue to develop this awesome library.
License
ShowdownJS v 2.0 is released under the MIT license. Previous versions are released under BSD.
Who uses Showdown (or a fork)
- GoogleCloudPlatform
- Meteor
- Stackexchange - forked as PageDown
- docular
- md-page
- QCObjects
- and some others...
Installation
Download tarball
You can download the latest release tarball directly from releases.
Bower
bower install showdown
npm (server-side)
npm install showdown
NuGet package
PM> Install-Package showdownjs
The NuGet Packages can be found here.
CDN
You can also use one of several CDNs available:
-
jsDelivr
https://cdn.jsdelivr.net/npm/showdown@<version tag>/dist/showdown.min.js -
cdnjs
https://cdnjs.cloudflare.com/ajax/libs/showdown/<version tag>/showdown.min.js -
unpkg
https://unpkg.com/showdown/dist/showdown.min.js
Note: replace <version tag> with an actual full length version you're interested in e.g. 1.9.0
Browser Compatibility
Showdown has been tested successfully with:
- Firefox 1.5 and 2.0
- Chrome 12.0
- Internet Explorer 6 and 7
- Safari 2.0.4
- Opera 8.54 and 9.10
- Netscape 8.1.2
- Konqueror 3.5.4
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.
Node compatibility
Showdown is intended to work on any supported Node.js version (see the Node.js releases schedule. The code may work with previous versions of Node.js, but no accomidations are made to ensure it does.
Legacy version
If you're looking for showdown v<1.0.0, you can find it in the legacy branch.
Changelog
You can check the full changelog
Extended documentation
Check our wiki pages for examples and a more in-depth documentation.
Quick Example
Node
var showdown = require('showdown'),
converter = new showdown.Converter(),
text = '# hello, markdown!',
html = converter.makeHtml(text);
Browser
var converter = new showdown.Converter(),
text = '# hello, markdown!',
html = converter.makeHtml(text);
Output
Both examples should output...
<h1 id="hellomarkdown">hello, markdown!</h1>
Options
You can change some of showdown's default behavior through options.
Setting options
Options can be set:
Globally
Setting a "global" option affects all instances of showdown
showdown.setOption('optionKey', 'value');
Locally
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'}); -
through the setOption() method
var converter = new showdown.Converter(); converter.setOption('optionKey', 'value');
Getting an option
Showdown provides 2 methods (both local and global) to retrieve previous set options.
getOption()
// Global
var myOption = showdown.getOption('optionKey');
//Local
var myOption = converter.getOption('optionKey');
getOptions()
// Global
var showdownGlobalOptions = showdown.getOptions();
//Local
var thisConverterSpecificOptions = converter.getOptions();
Retrieve the default options
You can get showdown's default options with:
var defaultOptions = showdown.getDefaultOptions();
Valid Options
-
omitExtraWLInCodeBlocks: (boolean) [default false] Omit the trailing newline in a code block. Ex:
This:
<code><pre>var foo = 'bar'; </pre></code>Becomes this:
<code><pre>var foo = 'bar';</pre></code> -
noHeaderId: (boolean) [default false] Disable the automatic generation of header ids. Setting to true overrides prefixHeaderId
-
customizedHeaderId: (boolean) [default false] Use text in curly braces as header id. (since v1.7.0) Example:
## Sample header {real-id} will use real-id as id -
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)
-
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
truewill add a generic 'section' prefix. -
rawPrefixHeaderId: (boolean) [default false] Setting this option to true will prevent showdown from modifying the prefix. This might result in malformed IDs (if, for instance, the " char is used in the prefix). Has no effect if prefixHeaderId is set to false. (since v 1.7.3)
-
rawHeaderId: (boolean) [default false] Remove only spaces, ' and " from generated header ids (including prefixes), replacing them with dashes (-). WARNING: This might result in malformed ids (since v1.7.3)
-
headerLevelStart: (integer) [default 1] Set the header starting level. For instance, setting this to 3 means that
# foowill be parsed as
<h3>foo</h3> -
parseImgDimensions: (boolean) [default false] Enable support for setting image dimensions from within markdown syntax. Examples:
 simple, assumes units are in px  sets the height to "auto"  Image with width of 80% and height of 5em -
simplifiedAutoLink: (boolean) [default false] Turning this option on will enable automatic linking to urls. This means that:
some text www.google.comwill be parsed as
<p>some text <a href="www.google.com">www.google.com</a> -
excludeTrailingPunctuationFromURLs: (boolean) [default false] This option excludes trailing punctuation from autolinking urls. Punctuation excluded:. ! ? ( ). Only applies if simplifiedAutoLink option is set totrue. -
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.Example:
some text with__underscores__in middlewill be parsed as
<p>some text with__underscores__in middle</p> -
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. -
strikethrough: (boolean) [default false] Enable support for strikethrough syntax.
~~strikethrough~~as<del>strikethrough</del> -
tables: (boolean) [default false] Enable support for tables syntax. Example:
| h1 | h2 | h3 | |:------|:-------:|--------:| | 100 | [a][1] | ![b][2] | | *foo* | **bar** | ~~baz~~ |See the wiki for more info
-
tablesHeaderId: (boolean) [default false] If enabled adds an id property to table headers tags.
-
ghCodeBlocks: (boolean) [default true] Enable support for GFM code block style.
-
tasklists: (boolean) [default false] Enable support for GFM tasklists. Example:
- [x] This task is done - [ ] This is still pending -
smoothLivePreview: (boolean) [default false] Prevents weird effects in live previews due to incomplete input
-
smartIndentationFix: (boolean) [default false] Tries to smartly fix indentation problems related to es6 template strings in the midst of indented code.
-
disableForced4SpacesIndentedSublists: (boolean) [default false] 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. (since v1.5.0)
-
simpleLineBreaks: (boolean) [default false] Parses line breaks as
<br>, without needing 2 spaces at the end of the line (since v1.5.1)a line wrapped in twoturns into:
<p>a line<br> wrapped in two</p> -
requireSpaceBeforeHeadingText: (boolean) [default false] Makes adding a space between
#and the header text mandatory (since v1.5.3) -
ghMentions: (boolean) [default false] Enables github @mentions, which link to the username mentioned (since v1.6.0)
-
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. Example:@tiviewith ghMentionsOption set to//mysite.com/{u}/profilewill result in<a href="//mysite.com/tivie/profile">@tivie</a> -
encodeEmails: (boolean) [default true] Enable 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.
-
openLinksInNewWindow: (boolean) [default false] Open all links in new windows (by adding the attribute
target="_blank"to<a>tags) (since v1.7.0) -
backslashEscapesHTMLTags: (boolean) [default false] Support for HTML Tag escaping. ex:
\<div>foo\</div>(since v1.7.2) -
emoji: (boolean) [default false] Enable emoji support. Ex:
this is a :smile: emojiFor more info on available emojis, see https://github.com/showdownjs/showdown/wiki/Emojis (since v.1.8.0) -
underline: (boolean) [default false] EXPERIMENTAL FEATURE Enable support for underline. Syntax is double or triple underscores ex:
__underlined word__. With this option enabled, underscores are no longer parses into<em>and<strong>. -
ellipsis: (boolean) [default true] Replaces three dots with the ellipsis unicode character.
-
completeHTMLDocument: (boolean) [default false] Outputs a complete html document, including
<html>,<head>and<body>tags' instead of an HTML fragment. (since v.1.8.5) -
metadata: (boolean) [default false] Enable support for document metadata (defined at the top of the document between
«««and»»»or between---and---). (since v.1.8.5)var conv = new showdown.Converter({metadata: true}); var html = conv.makeHtml(someMd); var metadata = conv.getMetadata(); // returns an object with the document metadata -
splitAdjacentBlockquotes: (boolean) [default false] Split adjacent blockquote blocks.(since v.1.8.6)
-
moreStyling: (boolean) [default false] Adds some useful classes for css styling. (since v2.0.1)
- Tasklists: Adds the class
task-list-item-completeto completed tasks items in GFM tasklists.
- Tasklists: Adds the class
NOTE: Please note that until version 1.6.0, all of these options are DISABLED by default in the cli tool.
Flavors
You can also use flavors or presets to set the correct options automatically, so that showdown behaves like popular markdown flavors.
Currently, the following flavors are available:
- original - original markdown flavor as in John Gruber's spec
- vanilla - showdown base flavor (as from v1.3.1)
- github - GFM (GitHub Flavored Markdown)
Global
showdown.setFlavor('github');
Instance
converter.setFlavor('github');
CLI Tool
Showdown also comes bundled with a Command Line Interface tool. You can check the CLI wiki page for more info
Integration with AngularJS
ShowdownJS project also provides seamlessly integration with AngularJS via a "plugin". Please visit https://github.com/showdownjs/ngShowdown for more information.
Integration with TypeScript
If you're using TypeScript you maybe want to use the types from DefinitelyTyped
Integration with SystemJS/JSPM
Integration with SystemJS can be obtained via the third party "system-md" plugin.
Integration with VueJS
To use ShowdownJS as a Vue component quickly, you can check vue-showdown.
XSS vulnerability
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. This, however, means XSS injection is quite possible.
Please refer to the wiki article Markdown's XSS Vulnerability (and how to mitigate it) for more information.
Extensions
Showdown allows additional functionality to be loaded via extensions. (you can find a list of known showdown extensions here) You can also find a boilerplate, to create your own extensions in this repository
Client-side Extension Usage
<script src="showdown.js" />
<script src="twitter-extension.js" />
var converter = new showdown.Converter({ extensions: ['twitter'] });
Server-side Extension Usage
var showdown = require('showdown'),
myExtension = require('myExtension'),
converter = new showdown.Converter({ extensions: ['myExtension'] });
Building
Building your clone of the repository is easy.
-
run
npm install. -
run
npx grunt build(seeGruntfile.js). This command:- Cleans the repo.
- Checks code quality (JSHint and ESLint).
- Runs tests.
- Creates the distributable and minified files in the
distfolder.
Tests
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:
npm install
Once installed the tests can be run from the project root using:
npm test
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.
Contributing
If you wish to contribute please read the following quick guide.
Want a Feature?
You can request a new feature by submitting an issue. If you would like to implement a new feature feel free to issue a Pull Request.
Pull requests (PRs)
PRs are awesome. However, before you submit your pull request consider the following guidelines:
-
Search GitHub for an open or closed Pull Request that relates to your submission. You don't want to duplicate effort.
-
When issuing PRs that change code, make your changes in a new git branch based on develop:
git checkout -b my-fix-branch develop -
Run the full test suite before submitting and make sure all tests pass (obviously =P).
-
Try to follow our coding style rules. Breaking them prevents the PR to pass the tests.
-
Refrain from fixing multiple issues in the same pull request. It's preferable to open multiple small PRs instead of one hard to review big one.
-
If the PR introduces a new feature or fixes an issue, please add the appropriate test case.
-
We use conventional commit notes to generate the changelog that follow the conventional changelog spec. It's extremely helpful if your commit messages adhere to these Commit Guidelines.
-
Don't forget to add your name to the CREDITS.md file. We like to give credit were it's due.
-
If we suggest changes then:
- Make the required updates.
- Re-run the test suite to ensure tests are still passing.
- Rebase your branch and force push to your GitHub repository (this will update your Pull Request):
git rebase develop -i git push origin my-fix-branch -f -
After your pull request is merged, you can safely delete your branch.
If you have time to contribute to this project, we feel obliged that you get credit for it. These rules enable us to review your PR faster and will give you appropriate credit in your GitHub profile. We thank you in advance for your contribution!
Joining the team
We're looking for members to help maintaining Showdown. Please see this issue to express interest or comment on this note.
Credits
Full credit list at https://github.com/showdownjs/showdown/blob/master/CREDITS.md
Showdown is powered by:
Top Related Projects
A markdown parser and compiler. Built for speed.
Markdown parser, done right. 100% CommonMark support, extensions, syntax plugins & high speed
CommonMark parser and renderer in JavaScript
Markdown parser, done right. Commonmark support, extensions, syntax plugins, high speed - all in one. Gulp and metalsmith plugins available. Used by Facebook, Docusaurus and many others! Use https://github.com/breakdance/breakdance for HTML-to-markdown conversion. Use https://github.com/jonschlinkert/markdown-toc to generate a table of contents.
A Markdown parser for javascript
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot