0
# Showdown
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: showdown
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install showdown`
10

11
## Core Imports
12

13
```javascript
14
const showdown = require('showdown');
15
```
16

17
ES6 modules:
18

19
```javascript
20
import showdown from 'showdown';
21
```
22

23
Browser (from CDN):
24

25
```html
26
<script src="https://cdn.jsdelivr.net/npm/showdown@2.1.0/dist/showdown.min.js"></script>
27
```
28

29
## Basic Usage
30

31
```javascript
32
const showdown = require('showdown');
33

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

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

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

47
With options:
48

49
```javascript
50
const converter = new showdown.Converter({
51
  tables: true,
52
  strikethrough: true,
53
  ghCodeBlocks: true
54
});
55
const html = converter.makeHtml('~~strikethrough~~ text');
56
```
57

58
## Architecture
59

60
Showdown is built around several key components:
61

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

69
## Capabilities
70

71
### Core Conversion
72

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

75
```javascript { .api }
76
// Constructor
77
new showdown.Converter(options?: ConverterOptions): Converter
78

79
// Core conversion methods
80
converter.makeHtml(text: string): string;
81
converter.makeMarkdown(src: string, HTMLParser?: any): string;
82
converter.makeMd(src: string, HTMLParser?: any): string; // alias for makeMarkdown
83
```
84

85
[Core Conversion](./core-conversion.md)
86

87
### Global Configuration
88

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

91
```javascript { .api }
92
showdown.setOption(key: string, value: any): showdown;
93
showdown.getOption(key: string): any;
94
showdown.getOptions(): ConverterOptions;
95
showdown.resetOptions(): void;
96
showdown.getDefaultOptions(simple?: boolean): ConverterOptions;
97
```
98

99
[Global Configuration](./global-configuration.md)
100

101
### Flavor Management
102

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

105
```javascript { .api }
106
showdown.setFlavor(name: string): void;
107
showdown.getFlavor(): string;
108
showdown.getFlavorOptions(name: string): ConverterOptions | undefined;
109
```
110

111
[Flavor Management](./flavor-management.md)
112

113
### Extension System
114

115
Plugin architecture for adding custom parsing behavior and output modifications.
116

117
```javascript { .api }
118
showdown.extension(name: string, ext?: Extension | Extension[] | Function): Extension[] | void;
119
showdown.getAllExtensions(): { [key: string]: Extension[] };
120
showdown.removeExtension(name: string): void;
121
showdown.resetExtensions(): void;
122
showdown.validateExtension(ext: Extension): boolean;
123
showdown.subParser(name: string, func?: Function): Function | void;
124
```
125

126
[Extension System](./extension-system.md)
127

128
### Instance Configuration
129

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

132
```javascript { .api }
133
converter.setOption(key: string, value: any): showdown.Converter;
134
converter.getOption(key: string): any;
135
converter.getOptions(): ConverterOptions;
136
converter.setFlavor(name: string): showdown.Converter;
137
converter.getFlavor(): string;
138
```
139

140
[Instance Configuration](./instance-configuration.md)
141

142
### Event System
143

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

146
```javascript { .api }
147
converter.listen(name: string, callback: EventCallback): showdown.Converter;
148
```
149

150
[Event System](./event-system.md)
151

152
### Command Line Interface
153

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

156
```bash { .api }
157
showdown makehtml [options]
158
```
159

160
[Command Line Interface](./cli.md)
161

162
## Types
163

164
```typescript { .api }
165
interface ConverterOptions {
166
  // Header options
167
  omitExtraWLInCodeBlocks?: boolean;
168
  noHeaderId?: boolean;
169
  prefixHeaderId?: string | boolean;
170
  rawPrefixHeaderId?: boolean;
171
  ghCompatibleHeaderId?: boolean;
172
  rawHeaderId?: boolean;
173
  headerLevelStart?: number;
174
  
175
  // Link and image options
176
  parseImgDimensions?: boolean;
177
  simplifiedAutoLink?: boolean;
178
  excludeTrailingPunctuationFromURLs?: boolean;
179
  openLinksInNewWindow?: boolean;
180
  backslashEscapesHTMLTags?: boolean;
181
  
182
  // Text processing options
183
  literalMidWordUnderscores?: boolean;
184
  literalMidWordAsterisks?: boolean;
185
  strikethrough?: boolean;
186
  underline?: boolean;
187
  emoji?: boolean;
188
  ghMentions?: boolean;
189
  ghMentionsLink?: string;
190
  
191
  // Structure options
192
  tables?: boolean;
193
  tablesHeaderId?: boolean;
194
  ghCodeBlocks?: boolean;
195
  tasklists?: boolean;
196
  smoothLivePreview?: boolean;
197
  simpleLineBreaks?: boolean;
198
  requireSpaceBeforeHeadingText?: boolean;
199
  encodeEmails?: boolean;
200
  
201
  // Advanced options
202
  smartIndentationFix?: boolean;
203
  disableForced4SpacesIndentedSublists?: boolean;
204
  metadata?: boolean;
205
  splitAdjacentBlockquotes?: boolean;
206
  ellipsis?: boolean;
207
  completeHTMLDocument?: boolean;
208
  
209
  // Extension loading
210
  extensions?: (string | Extension)[];
211
}
212

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

221
type EventCallback = (
222
  evtName: string,
223
  text: string,
224
  converter: showdown.Converter,
225
  options: ConverterOptions,
226
  globals: any
227
) => string | void;
228

229
interface Converter {
230
  makeHtml(text: string): string;
231
  makeMarkdown(src: string, HTMLParser?: any): string;
232
  makeMd(src: string, HTMLParser?: any): string;
233
  setOption(key: string, value: any): showdown.Converter;
234
  getOption(key: string): any;
235
  getOptions(): ConverterOptions;
236
  addExtension(extension: Extension, name?: string): showdown.Converter;
237
  useExtension(extensionName: string): showdown.Converter;
238
  setFlavor(name: string): showdown.Converter;
239
  getFlavor(): string;
240
  removeExtension(extension: Extension | string): showdown.Converter;
241
  getAllExtensions(): Extension[];
242
  listen(name: string, callback: EventCallback): showdown.Converter;
243
  getMetadata(raw?: boolean): any;
244
  getMetadataFormat(): string;
245
}
246
```