Showdown.js: Bidirectional Markdown and HTML Converter for JavaScript

What Showdown Does and Where It Runs

Showdown is a JavaScript converter that handles two directions: Markdown source to HTML output, and HTML input back to Markdown. The README states that it can be used client side in the browser or server side with Node.js. This bidirectionality is the feature that distinguishes it from most other Markdown libraries, which only convert Markdown to HTML.

The README traces the project's origins to the original works by John Gruber, the creator of Markdown, and notes that Showdown is based on John Fraser's earlier showdown.js port of Markdown.pl. Several well-known projects list themselves as users in the README, including Meteor and Stack Exchange (which forked Showdown as PageDown), and GoogleCloudPlatform.

The package is published under the MIT license. The npm package name is showdown. The package.json shows version 3.0.0-rc2 in the development branch. The last push to the repository was on 2026-09-21.

Installing Showdown in Node.js and the Browser

Install the npm package for server-side use:

npm install showdown

For browser projects that use Bower:

bower install showdown

For projects without a module bundler, the README provides two CDN URLs. Using jsDelivr:

https://cdn.jsdelivr.net/npm/showdown@<version tag>/dist/showdown.min.js

Or cdnjs:

https://cdnjs.cloudflare.com/ajax/libs/showdown/<version tag>/showdown.min.js

Replace <version tag> with the actual version, for example 1.9.0. The package.json exports field maps the browser condition to the ESM build at ./dist/showdown.esm.js and the CommonJS condition to ./dist/showdown.js, so bundlers that support the exports field will receive the correct build automatically.

Converting Markdown to HTML with the Converter API

The Converter constructor creates a conversion instance. In Node.js:

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

In the browser, the require call is omitted and the Converter is accessed directly from the showdown global object:

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

Both examples produce the same output:

    <h1 id="hello-markdown">hello, markdown!</h1>

The makeHtml method is the primary conversion entry point. It accepts a Markdown string and returns an HTML string. No asynchronous operation is involved: the call is synchronous.

Configuring Options Globally and Per Instance

Showdown exposes options both at the global level and per Converter instance. Setting a global option affects all instances created afterward:

showdown.setOption('optionKey', 'value');

Setting an option per instance, either through the constructor or the setOption method:

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

Or after construction:

var converter = new showdown.Converter();
converter.setOption('optionKey', 'value');

Retrieve options with getOption (for a single key) or getOptions (for all current settings). The getDefaultOptions method returns the library's baseline configuration before any overrides are applied.

The README documents several specific options. headerLevelStart controls the starting heading level: setting it to 3 means that a # heading in Markdown produces an <h3> element rather than <h1>. parseImgDimensions enables setting image dimensions from within Markdown syntax. headerIds controls whether id attributes are generated on headings, accepting false to disable them or an object with prefix and raw settings. simplifiedAutoLink turns on automatic URL linking.

The headerIds option replaces three older options that the README marks as removed: noHeaderId (now headerIds: false), prefixHeaderId (now headerIds: {prefix: 'foo'}), and rawHeaderId (now headerIds: {raw: true}). The prefix and raw settings can be combined in a single object. This consolidation was introduced to simplify the configuration surface while preserving all the previously available heading ID behaviors.

Browser Compatibility and Legacy Version

The README lists the browsers tested with Showdown: 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, and Konqueror 3.5.4. It also states that Showdown will work in any browser that supports ECMA 262 3rd Edition (JavaScript 1.5), and notes that the converter might even work in environments like Acrobat.

This wide compatibility reflects the library's age and its goal of running anywhere JavaScript runs. The package.json sets the Node.js engine requirement to >= 20, which applies to the npm package in its current form.

For projects running Showdown versions below 1.0.0, the README points to a legacy branch in the repository. Versions from 2.0.0 onward are MIT-licensed; the README notes that previous versions were under the BSD license.

Limitations: HTML-to-Markdown Fidelity and Maintenance Status

HTML-to-Markdown conversion is inherently lossy. HTML elements that have no Markdown equivalent, such as div, span, table styles, and inline CSS, cannot be represented accurately in standard Markdown. The resulting Markdown may contain raw HTML passthrough or lose semantic information. The README does not document which HTML constructs the reverse converter handles or where it falls back.

The most recent GitHub release is 2.1.0, published on 2022-04-21. The package.json carries a 3.0.0-rc2 version, suggesting a release candidate exists in the repository without a corresponding GitHub release tag. The push history shows activity on 2026-09-21, but users relying on stable release tags should check the releases page before updating dependencies.

Showdown is a pure conversion library with no Markdown editor, preview component, or real-time binding. Projects needing a complete editor experience with live preview must combine it with their own UI code.

The README also notes that the omitExtraWLInCodeBlocks option, when set to true, removes the trailing newline inside code block elements. This is relevant for projects that post-process the HTML output and compare strings, since the trailing newline can cause unexpected whitespace differences. The default value is false, so existing integrations are not affected unless the option is explicitly enabled.

Alternatives: marked and markdown-it

marked is a Markdown-to-HTML-only converter for Node.js and the browser with a focus on speed and spec compliance. It does not support HTML-to-Markdown conversion. marked uses a different option and extension API than Showdown, so switching requires changes to configuration code.

markdown-it is another Markdown-to-HTML converter that is widely used in documentation tools like VitePress. It has a plugin architecture for extending the parser with new syntax rules and is the underlying parser for several major documentation frameworks. Like marked, it does not support the reverse HTML-to-Markdown direction.

For projects that specifically need both directions of conversion in the browser, Showdown's bidirectionality is a concrete differentiator. For one-directional Markdown-to-HTML work, marked and markdown-it offer more actively maintained alternatives with larger plugin ecosystems.

Editorial conclusion

Showdown suits projects that need Markdown-to-HTML conversion without a build step, especially browser-based editors or CMS interfaces where user-entered Markdown must render live. The bidirectional HTML-to-Markdown path sets it apart from one-way converters when round-tripping content. The most recent GitHub release is 2.1.0 from 2022-04-21, though the repository has a package.json at version 3.0.0-rc2 and received a push on 2026-09-21. Verify which version tag is current before pinning a dependency.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. showdownjs/showdown on GitHub