0
# Markdown
1

2
A sensible Markdown parser for JavaScript that produces well-formed HTML through a multi-stage process with intermediate JSON representations. It supports both Node.js and browser environments, offers extensible dialect support, and includes a command-line tool for markdown-to-HTML conversion.
3

4
## Package Information
5

6
- **Package Name**: markdown
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install markdown`
10
- **Binary Command**: `md2html` (when installed globally with `-g`)
11

12
## Core Imports
13

14
```javascript
15
// Main API (recommended approach)
16
var markdown = require("markdown").markdown;
17

18
// Alternative import: top-level convenience export
19
var { parse } = require("markdown");  // Convenience alias for markdown.toHTML
20

21
// Access all functions through the main markdown object:
22
var actualParse = markdown.parse;         // Parse to JsonML tree
23
var toHTML = markdown.toHTML;             // Convert to HTML string  
24
var toHTMLTree = markdown.toHTMLTree;     // Convert to HTML JsonML
25
var renderJsonML = markdown.renderJsonML; // Render JsonML to string
26
```
27

28
For browser environments:
29

30
```html
31
<script src="lib/markdown.js"></script>
32
<script>
33
  // Available as window.markdown
34
  var html = markdown.toHTML("Hello *World*!");
35
</script>
36
```
37

38
## Basic Usage
39

40
```javascript
41
var markdown = require("markdown").markdown;
42

43
// Simple conversion - markdown string to HTML
44
var html = markdown.toHTML("Hello **World**!");
45
console.log(html); // <p>Hello <strong>World</strong>!</p>
46

47
// Two-step process for processing intermediate data
48
var tree = markdown.parse("Hello *World*!");
49
var htmlTree = markdown.toHTMLTree(tree);
50
var html = markdown.renderJsonML(htmlTree);
51

52
// Using different dialects
53
var html = markdown.toHTML("Hello **World**!", "Maruku");
54

55
// Alternative: use the convenience top-level parse export
56
var parse = require("markdown").parse; // Convenience alias for toHTML
57
var html = parse("Hello **World**!"); // Same as markdown.toHTML()
58
```
59

60
## Architecture
61

62
The markdown package uses a three-stage processing architecture:
63

64
1. **Parse Stage**: Converts markdown text into a JsonML tree representing markdown structure
65
2. **Transform Stage**: Converts the markdown JsonML tree into an HTML JsonML tree, resolving references and applying dialect rules  
66
3. **Render Stage**: Serializes the HTML JsonML tree into well-formed HTML strings
67

68
Key architectural components:
69

70
- **Markdown Class**: Core processor with dialect support and block/inline parsing
71
- **Dialect System**: Extensible rule sets (Gruber, Maruku) defining parsing behavior
72
- **JsonML Representation**: Intermediate tree format enabling manipulation between stages
73
- **Block/Inline Processors**: Separate rule engines for block-level and inline elements
74
- **Reference Resolution**: Link and image reference processing with attribute management
75

76
## Capabilities
77

78
### Core Parsing and Conversion
79

80
Essential functions for converting markdown to HTML with optional intermediate processing.
81

82
```javascript { .api }
83
/**
84
 * Parse markdown text into JsonML tree representation
85
 * @param {string} source - Markdown text to parse
86
 * @param {string|Object} dialect - Dialect name or dialect object (default: "Gruber")
87
 * @returns {Array} JsonML tree representing markdown structure
88
 */
89
function parse(source, dialect);
90

91
/**
92
 * Convert markdown text or JsonML tree directly to HTML string
93
 * @param {string|Array} source - Markdown text or JsonML tree
94
 * @param {string|Object} dialect - Dialect name or dialect object (default: "Gruber")
95
 * @param {Object} options - Processing options
96
 * @returns {string} HTML string
97
 */
98
function toHTML(source, dialect, options);
99

100
/**
101
 * Convert markdown to HTML JsonML tree for processing
102
 * @param {string|Array} input - Markdown text or markdown JsonML tree
103
 * @param {string|Object} dialect - Dialect name or dialect object (default: "Gruber")
104
 * @param {Object} options - Processing options
105
 * @returns {Array} JsonML tree representing HTML structure
106
 */
107
function toHTMLTree(input, dialect, options);
108

109
/**
110
 * Render JsonML tree to well-formed HTML/XML string
111
 * @param {Array} jsonml - JsonML array to render
112
 * @param {Object} options - Rendering options
113
 * @param {boolean} options.root - Include root element in output (default: false)
114
 * @returns {string} HTML/XML string
115
 */
116
function renderJsonML(jsonml, options);
117
```
118

119
[Core API](./core-api.md)
120

121
### Markdown Processor Class
122

123
Advanced processing with full control over parsing stages and dialect customization.
124

125
```javascript { .api }
126
/**
127
 * Create new Markdown processor instance
128
 * @param {string|Object} dialect - Dialect name or dialect object
129
 * @constructor
130
 * @throws {Error} When dialect is unknown
131
 */
132
function Markdown(dialect);
133

134
// Key instance methods
135
/**
136
 * Parse source into JsonML markdown tree
137
 * @param {string|Array} source - Markdown source or block array
138
 * @param {Array} custom_root - Custom root node (optional)
139
 * @returns {Array} JsonML markdown tree
140
 */
141
Markdown.prototype.toTree = function(source, custom_root);
142

143
/**
144
 * Process individual block and return JsonML nodes
145
 * @param {string} block - Block to process
146
 * @param {Array} next - Following blocks
147
 * @returns {Array} Array of JsonML nodes
148
 */
149
Markdown.prototype.processBlock = function(block, next);
150

151
/**
152
 * Process inline content within a block
153
 * @param {string} block - Block content to process
154
 * @returns {Array} Processed inline content array
155
 */
156
Markdown.prototype.processInline = function(block);
157
```
158

159
[Markdown Class](./markdown-class.md)
160

161
### Dialect System
162

163
Extensible parsing rules supporting Gruber (default) and Maruku dialects with custom dialect creation.
164

165
```javascript { .api }
166
// Built-in dialects
167
var Markdown.dialects.Gruber; // Default Gruber dialect
168
var Markdown.dialects.Maruku; // Extended Maruku dialect
169

170
/**
171
 * Create dialect subclass with prototype inheritance
172
 * @param {Object} d - Base dialect to extend
173
 * @returns {Object} New dialect with inherited block and inline processors
174
 */
175
function Markdown.subclassDialect(d);
176

177
/**
178
 * Build processing order for block rules in dialect
179
 * @param {Object} d - Dialect block rules object
180
 */
181
function Markdown.buildBlockOrder(d);
182

183
/**
184
 * Build regex patterns for inline rules in dialect
185
 * @param {Object} d - Dialect inline rules object
186
 */
187
function Markdown.buildInlinePatterns(d);
188
```
189

190
[Dialects](./dialects.md)
191

192
### Command Line Interface
193

194
CLI tool for converting markdown files to HTML with dialect selection.
195

196
```javascript { .api }
197
// Command: md2html [options] [file]
198
// Options:
199
//   --dialect=DIALECT  Choose "Gruber" (default) or "Maruku"
200
//   --help            Show usage information
201
// 
202
// Input: File path or stdin (-)
203
// Output: HTML to stdout
204
```
205

206
**Usage Examples:**
207
```bash
208
# Convert file
209
md2html document.md > document.html
210

211
# Use Maruku dialect  
212
md2html --dialect=Maruku document.md
213

214
# Process from stdin
215
echo "# Hello World" | md2html
216
```
217

218
[Command Line](./command-line.md)
219

220
## Types
221

222
```javascript { .api }
223
/**
224
 * JsonML (JSON Markup Language) format for representing structured markup
225
 * 
226
 * Basic Structure: [tag_name, attributes, ...children]
227
 * - tag_name: String - HTML/XML tag name
228
 * - attributes: Object - Key-value pairs for attributes (can be empty {})
229
 * - children: Mixed - Text strings or nested JsonML arrays
230
 * 
231
 * Examples:
232
 * ["p", {}, "Simple paragraph"]
233
 * ["p", { class: "highlight" }, "Paragraph with class"]
234
 * ["p", {}, "Hello ", ["strong", {}, "World"], "!"]
235
 * ["div", {}, ["h1", {}, "Title"], ["p", {}, "Content"]]
236
 */
237

238
/**
239
 * Block object with metadata
240
 * @typedef {string} Block
241
 * @property {string} trailing - Trailing whitespace/newlines
242
 * @property {number} lineNumber - Source line number
243
 * @property {Function} inspect - Debug inspection method
244
 * @property {Function} toSource - Source serialization method
245
 */
246

247
/**
248
 * Dialect object defining parsing rules
249
 * @typedef {Object} Dialect
250
 * @property {Object} block - Block-level processing rules
251
 * @property {Object} inline - Inline processing rules
252
 * @property {Array} block.__order__ - Block processor execution order
253
 * @property {string} inline.__patterns__ - Inline pattern regex
254
 * @property {Function} inline.__call__ - Main inline processor
255
 */
256

257
/**
258
 * Processing options for HTML conversion
259
 * @typedef {Object} ProcessingOptions
260
 * @property {Function} preprocessTreeNode - Tree preprocessing function
261
 */
262

263
/**
264
 * Rendering options for JsonML output
265
 * @typedef {Object} RenderingOptions
266
 * @property {boolean} root - Include root element in output
267
 */
268
```