Guide · Open source

How to use Showdown: Markdown to HTML in JavaScript

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Showdown is a JavaScript library that turns Markdown, a plain-text formatting syntax, into HTML, and can also convert HTML back into Markdown. It runs in a web browser or on a server with Node.js. This guide shows you how to install it, convert text with a Converter object, and turn on common options such as tables and header ids.

Showdownshowdownjs/showdown · ★ 14.9k · MIT Install options & downloads

Quick start

1Install the package. Run npm install showdown in your Node.js project, or load showdown.min.js from a CDN in the browser.
2Load the library. Use require('showdown') in Node, or the global showdown object in the browser.
3Create a converter. Call new showdown.Converter() to make a converter instance.
4Convert your Markdown. Pass your Markdown string to converter.makeHtml() and receive HTML back.
5Set options if needed. Pass options to the constructor or use setOption() to enable tables, header ids or image sizing.

Install Showdown with npm or a CDN

For server-side use with Node.js, install Showdown from npm. The README lists npm as the install method for server use, and Node.js is the prerequisite for that setup.

For the browser, the README lists CDN links from jsDelivr, cdnjs and unpkg that point to a dist/showdown.min.js file. It also says to replace the version tag with a full-length version number, which you choose yourself. Other install routes are Bower, NuGet and downloading the release tarball.

Node.js: npm install showdown
Browser: load showdown.min.js from one of the listed CDNs

npm install showdown

Convert Markdown to HTML with a Converter

Create a Converter object and call makeHtml() with your Markdown string. The README example uses the text '# hello, markdown!' and shows that both Node and browser code produce the same heading output.

In Node, you load the library with require('showdown'). In the browser, the library is available as the global showdown object once the script is loaded.

var showdown  = require('showdown'),
    converter = new showdown.Converter(),
    text      = '# hello, markdown!',
    html      = converter.makeHtml(text);

Set options globally or per converter

Options change some default behavior. A global option affects all Converter instances and is set with showdown.setOption(). A local option affects only one converter and can be passed to the constructor or set with converter.setOption().

You can read options back with getOption() and getOptions(), and get the defaults with showdown.getDefaultOptions().

Global: showdown.setOption('optionKey', 'value')
Local via constructor: new showdown.Converter({optionKey: 'value'})
Local via method: converter.setOption('optionKey', 'value')

var converter = new showdown.Converter({optionKey: 'value'});

Enable tables, header ids and image sizing

The tables option is off by default and must be set to true to use table syntax. The headerIds option controls the id attribute on headings: the default generates GitHub-style ids, false removes ids, and an object accepts a prefix and a raw flag. The README warns that raw: true can produce malformed ids.

parseImgDimensions is also off by default. When enabled, it lets you set image size inside Markdown, such as =100x80 for pixels or =80%x5em for percentages. The strikethrough option is on by default and converts ~~text~~ to del tags.

tables: default false
headerIds: default {}; false disables ids
headerLevelStart: default 1; set 3 to start headings at h3
parseImgDimensions: default false
simplifiedAutoLink: default false, turns www. addresses into links
literalMidWordUnderscores: default false

var converter = new showdown.Converter({tables: true, headerIds: {prefix: 'section-'}});

Know the limits before you adopt it

Showdown is a library, not an editor app, so you need code to use it. The README says it aims to work on supported Node.js versions. It also says the library follows GitHub-style ids but does not claim full GitHub rendering compatibility.

The browser compatibility section lists very old browser versions as tested, and gives no current testing details, so check it in the browsers you need to support.

Not a ready-made Markdown editor
Not a promise of exact GitHub rendering
Check current browser support yourself

What people use it for

Rendering user-written comments or posts as formatted HTML in a web page
Converting Markdown documentation files into HTML on a Node.js server
Converting HTML content back into Markdown with the two-way converter
Enabling table syntax in Markdown content for a web app

Frequently asked questions

How do I install Showdown?

For server use, run npm install showdown in a Node.js project. For the browser, the README lists CDN links from jsDelivr, cdnjs and unpkg, plus Bower, NuGet and a release tarball.

Is Showdown free to use?

Showdown is released under the MIT license from version 2.0 onwards. Earlier versions were released under BSD. The README also says the library is free and asks for optional donations to support maintenance.

What do I need to run Showdown?

The README lists Node.js as the prerequisite for server-side use. For browser use, you load the library script in a page.

Does Showdown convert HTML to Markdown?

Yes. The README says Showdown is bidirectional and can convert Markdown to HTML and HTML to Markdown.

Does Showdown support tables?

Yes, but the tables option is false by default. You must set it to true to use the table syntax shown in the README.

How does Showdown compare to marked, markdown-it or remark?

The source does not compare these projects, so this guide cannot say which is faster or more accurate. Showdown's distinguishing feature from the README is two-way conversion between Markdown and HTML.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Showdown suits JavaScript developers who need Markdown rendering in a web page or Node.js script, especially if they also need HTML converted back to Markdown. Pick something else if you want a ready-made Markdown editor app, exact GitHub rendering, or a library with clearly documented current browser support.

Install options & downloads