Showdown Markdown to HTML Converter

Strikethrough is enabled by default in the vanilla flavor. Use two tildes (~~) around text to produce a <s /> element, similar to GitHub Flavored Markdown (GFM).

a ~~strikethrough~~ element

The event system is the foundation for modern Showdown extensions (specifically listener extensions). As Showdown parses a document, sub-parsers emit events during the conversion process. A listener extension can subscribe to these events to inspect or modify the conversion in flight.

The lifecycle of an event is as follows:

1. A sub-parser emits an event (potentially a batch of events).
2. A listener extension registers for a specific event type.
3. The extension receives an event object and can modify certain properties to change the sub-parser's behavior or output.
4. The extension returns the modified event object to the converter.
5. The converter passes the event object to the next extension in the chain.

In makeMarkdown(), you can override how a specific HTML node is converted to Markdown by using the onStart event of its corresponding sub-parser.

If you set evt.output to a non-empty string within an onStart listener, that string is used as the result and the default rendering of the node is skipped. The matching onEnd event will still run, but the default logic is bypassed. This is the makeMarkdown equivalent of the onCapture behavior in makeHtml.

// Render every <a> as bare text instead of a Markdown link
converter.listen('makeMarkdown.links.onStart', function (evt) {
  evt.output = evt.matches.node.textContent;
  return evt;
});

Showdown's list implementation has two specific behaviors to note:

1. Loose vs Tight Lists: If any list item is separated from another by a blank line, Showdown wraps all items in <p> tags. To avoid this, ensure items are adjacent.
2. Four-space Indentation: Nested lists require an indentation of four spaces (or one tab) per level. This is consistent with the original spec but differs from GFM/CommonMark. You can relax this using the disableForced4SpacesIndentedSublists option.

* Item 1

* Item 2 (This will trigger <p> tags for all items in the list)

The gfm flavor in Showdown is built on top of the commonmark base and adds the following extensions:

• Tables: Pipe tables with support for per-column alignment.
• Task lists: Checkboxes using - [ ] and - [x] syntax.
• Strikethrough: Text decoration using ~~text~~.
• Autolink literals: Bare URLs are converted to links. Note: Showdown also links <www.…> inside angle brackets, which is a deviation from the standard GFM spec.
• @-mentions and emoji: Support for mentions and emoji syntax (e.g., :smile:).
• Footnotes: Support for [^id] references and definitions (also reversible via makeMarkdown).

When an event is triggered, the listener receives an event object. A key property of this object is matches, which contains the text captured by the sub-parser.

Note that the structure of matches varies depending on which sub-parser emitted the event. Additionally, some properties within matches are read-only; these are identified by a leading underscore (e.g., _wholeMatch).

// Example of a blockquote `onCapture` event object
{
  _wholeMatch: "> some awesome quote",
  blockquote: "some awesome quote"
}

Showdown extensions allow you to add custom functionality to the Markdown conversion process. There are two primary modes of operation:

1. Listener extensions (Recommended): These use the Showdown event system to hook into sub-parsers. They can inspect or modify captures, matches, attributes, and output mid-conversion. This mode provides high precision for complex transformations.
2. Legacy lang/output extensions (Deprecated): These are older modes that use regex/replace or a filter callback to rewrite text either before parsing (lang) or after parsing (output). While they still function, they are now thin wrappers over document-level events and will trigger a deprecation warning. Use listener extensions for all new development.

The onStart event is emitted when a sub-parser starts. It is always called unless the sub-parser is disabled via options.

When to use: Use this event when you want to change the input passed to the sub-parser.

Warning: The input property contains the full text that was passed to the converter, not just the fragment relevant to the sub-parser. To pass modified text down the chain, write to the output property.

// Example of the properties available in onStart
// { 
//   input: 'full text string', 
//   output: 'modified text string', 
//   regexp: null, 
//   matches: null, 
//   attributes: null 
// }