Showdown Markdown to HTML Converter

Common errors

• ReferenceError: showdown is not defined

  cause The Showdown library was not properly loaded in the browser environment, or accessed incorrectly in a module context.
  fix In browsers, ensure you have included `<script src="path/to/showdown.min.js"></script>` before attempting to use it. In a module, ensure it's imported via `require` or `import`.

• TypeError: showdown.Converter is not a constructor

  cause Attempted to call `showdown.Converter()` as a function instead of instantiating it with `new`.
  fix Always use `new showdown.Converter()` to create a new converter instance.

• Error: Unknown option: --strikethrough (or other CLI options)

  cause Using the pre-v2.1.0 CLI syntax for extra options after upgrading to Showdown 2.1.0 or newer.
  fix For CLI options like `strikethrough` or `emoji`, use the `-c` flag for each option. E.g., `showdown makehtml -i input.md -o output.html -c strikethrough -c emoji`.

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require()` in an ECMAScript Module (ESM) context (e.g., a Node.js file with `"type": "module"` in `package.json`).
  fix Refactor your import statements to use ESM syntax: `import { Converter } from 'showdown';` and then `new Converter();`.

Warnings

• breaking The command-line interface (CLI) for `showdown` changed how 'extra options' are passed. Instead of direct flags like `--strikethrough`, you must now use the `-c` flag for each option.
  Fix: Update your CLI commands. For example, `showdown makehtml -i foo.md -o bar.html --strikethrough --emoji` becomes `showdown makehtml -i foo.md -o bar.html -c strikethrough -c emoji`.
• breaking Supported Node.js versions were updated to align with the official Node.js release schedule. This dropped support for older, unmaintained Node.js versions.
  Fix: Ensure your Node.js environment is running a version in the 'Current', 'Active', or 'Maintenance' phase (e.g., 12.x, 14.x, 16.x, 17.x at the time of the 2.0.0 release). Upgrade Node.js if necessary.
• breaking The library's license changed from BSD to MIT with the 2.0.0 release. This primarily affects legal compliance and redistribution terms.
  Fix: Review the new MIT license terms if your project's licensing or distribution depends on Showdown's license.
• gotcha The `yargs` dependency, used for CLI parsing, was updated to mitigate security vulnerabilities. While primarily an internal change, it could potentially introduce subtle behavioral differences or require adjustments if you relied on specific `yargs` behaviors in custom CLI scripts.
  Fix: Test your CLI scripts and custom integrations thoroughly after upgrading to ensure no unexpected changes in argument parsing or behavior.
• gotcha While Showdown claims compatibility with very old browsers (e.g., IE6, Firefox 1.5), using it in such environments may not be practical or fully functional with modern Markdown features. Modern development typically targets more recent browser versions.
  Fix: For new projects, ensure you are testing against contemporary browser versions. If targeting extremely old browsers, be prepared for potential edge cases or feature limitations.

Install

• npm install showdown npm
• yarn add showdown yarn
• pnpm add showdown pnpm

Imports

• Converter
  wrong:

  import showdown from 'showdown';

  correct:

  import { Converter } from 'showdown';

  For modern ESM environments (e.g., Node.js with type:module or bundlers), `Converter` is a named export. The default export might be undefined or an unexpected object in some setups.
• showdown (CommonJS object)
  wrong:

  const { Converter } = require('showdown');

  correct:

  const showdown = require('showdown');

  In CommonJS (Node.js < 14, or CJS modules), `require('showdown')` returns an object containing the `Converter` class and other utilities. The `Converter` class is accessed as `showdown.Converter`.
• Converter (Global in browser)
  wrong:

  const converter = new Converter();

  correct:

  const converter = new showdown.Converter();

  When loaded directly in a browser via a `<script>` tag (e.g., from CDN), the `showdown` object is exposed globally on `window`, containing the `Converter` class.

Quickstart

This quickstart demonstrates how to initialize the Showdown converter with several common options (emoji, strikethrough, tables, tasklists) and convert a Markdown string into an HTML string using CommonJS syntax.

const showdown = require('showdown');

const converter = new showdown.Converter({
    emoji: true,
    strikethrough: true,
    tables: true,
    tasklists: true,
    openLinksInNewWindow: true
});

const markdownText = `
# Hello, Showdown!

This is a **Markdown** example with some common features.

- List item 1
- List item 2
  - Sub-item

~~Strikethrough text~~ and an :emoji:! 🎉

| Header 1 | Header 2 |
|---|---|
| Cell 1 | Cell 2 |

- [x] Task 1 (completed)
- [ ] Task 2 (pending)

[Visit ShowdownJS](https://showdownjs.com/)
`;

const html = converter.makeHtml(markdownText);

console.log(html);
// Expected output: An HTML string representing the converted Markdown.