or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdcore-conversion.mdevent-system.mdextension-system.mdflavor-management.mdglobal-configuration.mdindex.mdinstance-configuration.md
tile.json

tessl/npm-showdown

A Markdown to HTML converter written in Javascript

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/showdown@2.1.x

To install, run

npx @tessl/cli install tessl/npm-showdown@2.1.0

index.mddocs/

Showdown

Showdown is a JavaScript Markdown to HTML converter, based on the original works by John Gruber. It can be used client-side (in the browser) or server-side (with Node.js). Showdown provides extensive customization options, extension support, and multiple flavors to match different Markdown dialects including GitHub Flavored Markdown.

Package Information

  • Package Name: showdown
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install showdown

Core Imports

const showdown = require('showdown');

ES6 modules:

import showdown from 'showdown';

Browser (from CDN):

<script src="https://cdn.jsdelivr.net/npm/showdown@2.1.0/dist/showdown.min.js"></script>

Basic Usage

const showdown = require('showdown');

// Create converter instance
const converter = new showdown.Converter();

// Convert Markdown to HTML
const text = '# hello, markdown!';
const html = converter.makeHtml(text);
console.log(html); // <h1 id="hellomarkdown">hello, markdown!</h1>

// Convert HTML back to Markdown
const markdown = converter.makeMarkdown('<h1>Hello World</h1>');
console.log(markdown); // # Hello World

With options:

const converter = new showdown.Converter({
  tables: true,
  strikethrough: true,
  ghCodeBlocks: true
});
const html = converter.makeHtml('~~strikethrough~~ text');

Architecture

Showdown is built around several key components:

  • Core API: Static methods for global configuration and extension management
  • Converter Class: Instance-based conversion with local options and extensions
  • Extension System: Plugin architecture supporting language and output extensions
  • Options System: Comprehensive configuration with predefined flavors
  • SubParser System: Modular parsing components for different Markdown elements
  • Flavor System: Preset configurations (vanilla, github, ghost, original, allOn)

Capabilities

Core Conversion

Primary functionality for converting between Markdown and HTML formats. The Converter class provides the main conversion methods.

// Constructor
new showdown.Converter(options?: ConverterOptions): Converter

// Core conversion methods
converter.makeHtml(text: string): string;
converter.makeMarkdown(src: string, HTMLParser?: any): string;
converter.makeMd(src: string, HTMLParser?: any): string; // alias for makeMarkdown

Core Conversion

Global Configuration

Static methods for managing global options that affect all Showdown instances unless overridden locally.

showdown.setOption(key: string, value: any): showdown;
showdown.getOption(key: string): any;
showdown.getOptions(): ConverterOptions;
showdown.resetOptions(): void;
showdown.getDefaultOptions(simple?: boolean): ConverterOptions;

Global Configuration

Flavor Management

Preset configuration bundles that apply sets of options for compatibility with different Markdown dialects.

showdown.setFlavor(name: string): void;
showdown.getFlavor(): string;
showdown.getFlavorOptions(name: string): ConverterOptions | undefined;

Flavor Management

Extension System

Plugin architecture for adding custom parsing behavior and output modifications.

showdown.extension(name: string, ext?: Extension | Extension[] | Function): Extension[] | void;
showdown.getAllExtensions(): { [key: string]: Extension[] };
showdown.removeExtension(name: string): void;
showdown.resetExtensions(): void;
showdown.validateExtension(ext: Extension): boolean;
showdown.subParser(name: string, func?: Function): Function | void;

Extension System

Instance Configuration

Methods for managing options on individual Converter instances, overriding global settings.

converter.setOption(key: string, value: any): showdown.Converter;
converter.getOption(key: string): any;
converter.getOptions(): ConverterOptions;
converter.setFlavor(name: string): showdown.Converter;
converter.getFlavor(): string;

Instance Configuration

Event System

Event listeners for hooking into the conversion process at various stages.

converter.listen(name: string, callback: EventCallback): showdown.Converter;

Event System

Command Line Interface

CLI tool for converting Markdown files to HTML with full option support.

showdown makehtml [options]

Command Line Interface

Types

interface ConverterOptions {
  // Header options
  omitExtraWLInCodeBlocks?: boolean;
  noHeaderId?: boolean;
  prefixHeaderId?: string | boolean;
  rawPrefixHeaderId?: boolean;
  ghCompatibleHeaderId?: boolean;
  rawHeaderId?: boolean;
  headerLevelStart?: number;
  
  // Link and image options
  parseImgDimensions?: boolean;
  simplifiedAutoLink?: boolean;
  excludeTrailingPunctuationFromURLs?: boolean;
  openLinksInNewWindow?: boolean;
  backslashEscapesHTMLTags?: boolean;
  
  // Text processing options
  literalMidWordUnderscores?: boolean;
  literalMidWordAsterisks?: boolean;
  strikethrough?: boolean;
  underline?: boolean;
  emoji?: boolean;
  ghMentions?: boolean;
  ghMentionsLink?: string;
  
  // Structure options
  tables?: boolean;
  tablesHeaderId?: boolean;
  ghCodeBlocks?: boolean;
  tasklists?: boolean;
  smoothLivePreview?: boolean;
  simpleLineBreaks?: boolean;
  requireSpaceBeforeHeadingText?: boolean;
  encodeEmails?: boolean;
  
  // Advanced options
  smartIndentationFix?: boolean;
  disableForced4SpacesIndentedSublists?: boolean;
  metadata?: boolean;
  splitAdjacentBlockquotes?: boolean;
  ellipsis?: boolean;
  completeHTMLDocument?: boolean;
  
  // Extension loading
  extensions?: (string | Extension)[];
}

interface Extension {
  type: 'lang' | 'output' | 'listener';
  filter?: (text: string, converter: showdown.Converter, options: ConverterOptions) => string;
  regex?: RegExp | string;
  replace?: string | Function;
  listeners?: { [eventName: string]: EventCallback };
}

type EventCallback = (
  evtName: string,
  text: string,
  converter: showdown.Converter,
  options: ConverterOptions,
  globals: any
) => string | void;

interface Converter {
  makeHtml(text: string): string;
  makeMarkdown(src: string, HTMLParser?: any): string;
  makeMd(src: string, HTMLParser?: any): string;
  setOption(key: string, value: any): showdown.Converter;
  getOption(key: string): any;
  getOptions(): ConverterOptions;
  addExtension(extension: Extension, name?: string): showdown.Converter;
  useExtension(extensionName: string): showdown.Converter;
  setFlavor(name: string): showdown.Converter;
  getFlavor(): string;
  removeExtension(extension: Extension | string): showdown.Converter;
  getAllExtensions(): Extension[];
  listen(name: string, callback: EventCallback): showdown.Converter;
  getMetadata(raw?: boolean): any;
  getMetadataFormat(): string;
}