0
# Markdown Class
1

2
Advanced markdown processing with full control over parsing stages, dialect customization, and block-level processing.
3

4
## Capabilities
5

6
### Markdown Constructor
7

8
Create a new Markdown processor instance with specified dialect.
9

10
```javascript { .api }
11
/**
12
 * Create new Markdown processor instance
13
 * @param {string|Object} dialect - Dialect name ("Gruber", "Maruku") or dialect object
14
 * @constructor
15
 * @throws {Error} When dialect is unknown
16
 */
17
function Markdown(dialect);
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
var { Markdown } = require("markdown").markdown;
24

25
// Create with default Gruber dialect
26
var md = new Markdown();
27

28
// Create with specific dialect
29
var md = new Markdown("Maruku");
30

31
// Create with custom dialect object
32
var customDialect = {
33
  block: { /* custom block rules */ },
34
  inline: { /* custom inline rules */ }
35
};
36
var md = new Markdown(customDialect);
37

38
// Error handling
39
try {
40
  var md = new Markdown("UnknownDialect");
41
} catch (e) {
42
  console.log(e.message); // "Unknown Markdown dialect 'UnknownDialect'"
43
}
44
```
45

46
### ToTree Method
47

48
Parse source into JsonML markdown tree with optional custom root node.
49

50
```javascript { .api }
51
/**
52
 * Parse source into JsonML markdown tree
53
 * @param {string|Array} source - Markdown source text or block array from split_blocks()
54
 * @param {Array} custom_root - Custom root node (optional, default: ["markdown"])
55
 * @returns {Array} JsonML markdown tree
56
 */
57
Markdown.prototype.toTree = function(source, custom_root);
58
```
59

60
**Usage Examples:**
61

62
```javascript
63
var md = new Markdown();
64

65
// Basic parsing
66
var tree = md.toTree("Hello **World**!");
67
// Returns: ["markdown", {}, ["para", {}, "Hello ", ["strong", {}, "World"], "!"]]
68

69
// With custom root
70
var tree = md.toTree("Hello World", ["custom_root"]);
71
// Returns: ["custom_root", "Hello World"]
72

73
// Processing pre-split blocks
74
var blocks = md.split_blocks("# Header\n\nParagraph");
75
var tree = md.toTree(blocks);
76
```
77

78
### ProcessBlock Method
79

80
Process individual block element and return JsonML nodes.
81

82
```javascript { .api }
83
/**
84
 * Process individual block and return JsonML nodes
85
 * @param {string} block - Block content to process (enhanced string with metadata)
86
 * @param {Array} next - Array of following blocks for lookahead processing
87
 * @returns {Array} Array of JsonML nodes representing the processed block
88
 */
89
Markdown.prototype.processBlock = function(block, next);
90
```
91

92
**Usage Examples:**
93

94
```javascript
95
var md = new Markdown();
96

97
// Process single block
98
var blocks = md.split_blocks("# Header\n\nParagraph");
99
var headerResult = md.processBlock(blocks[0], blocks.slice(1));
100
// Returns: [["header", { level: 1 }, "Header"]]
101

102
// Process with context (for lists, blockquotes, etc.)
103
var blocks = md.split_blocks("- Item 1\n- Item 2");
104
var listResult = md.processBlock(blocks[0], blocks.slice(1));
105
// Returns array with bulletlist JsonML
106
```
107

108
### ProcessInline Method
109

110
Process inline content within a block using dialect inline rules.
111

112
```javascript { .api }
113
/**
114
 * Process inline content within a block
115
 * @param {string} block - Block content to process for inline elements
116
 * @returns {Array} Array of processed inline content (strings and JsonML nodes)
117
 */
118
Markdown.prototype.processInline = function(block);
119
```
120

121
**Usage Examples:**
122

123
```javascript
124
var md = new Markdown();
125

126
// Process inline elements
127
var result = md.processInline("Hello **bold** and *italic* text");
128
// Returns: ["Hello ", ["strong", {}, "bold"], " and ", ["em", {}, "italic"], " text"]
129

130
// Process links and images
131
var result = md.processInline("Visit [link](http://example.com) and see ![image](img.jpg)");
132
// Returns: ["Visit ", ["link", { href: "http://example.com" }, "link"], " and see ", ["img", { alt: "image", href: "img.jpg" }]]
133
```
134

135
### Split Blocks Method
136

137
Split input text into block-level chunks with metadata.
138

139
```javascript { .api }
140
/**
141
 * Split input into block-level chunks with metadata
142
 * @param {string} input - Markdown input text
143
 * @param {number} startLine - Starting line number for tracking (optional)
144
 * @returns {Array} Array of enhanced block strings with trailing and lineNumber properties
145
 */
146
Markdown.prototype.split_blocks = function(input, startLine);
147
```
148

149
**Usage Examples:**
150

151
```javascript
152
var md = new Markdown();
153

154
// Split markdown into blocks
155
var blocks = md.split_blocks("# Header\n\nParagraph\n\n    Code block");
156
console.log(blocks.length); // 3
157

158
// Each block has metadata
159
console.log(blocks[0].toString()); // "# Header"
160
console.log(blocks[0].trailing);   // "\n\n"
161
console.log(blocks[0].lineNumber); // 1
162

163
console.log(blocks[1].toString()); // "Paragraph"
164
console.log(blocks[1].trailing);   // "\n\n"
165
console.log(blocks[1].lineNumber); // 3
166
```
167

168
### Debug Method
169

170
Debug logging method for development and troubleshooting.
171

172
```javascript { .api }
173
/**
174
 * Debug logging method (noop by default)
175
 * @param {...*} args - Variable arguments for logging
176
 * @returns {undefined}
177
 */
178
Markdown.prototype.debug = function(/* ...args */);
179
```
180

181
**Usage Examples:**
182

183
```javascript
184
var md = new Markdown();
185

186
// Debug output (if print or console.log available)
187
md.debug("Processing block:", blockContent);
188

189
// Enable custom debug output
190
md.debug = function() {
191
  var args = Array.prototype.slice.call(arguments);
192
  console.log("MARKDOWN DEBUG:", args.join(" "));
193
};
194
```
195

196
### Loop Regex Over Block Method
197

198
Apply regular expression repeatedly over block content with callback processing.
199

200
```javascript { .api }
201
/**
202
 * Apply regex repeatedly over block with callback
203
 * @param {RegExp} re - Regular expression to apply (should not use /g flag)
204
 * @param {string} block - Block content to process
205
 * @param {Function} cb - Callback function called for each match
206
 * @returns {string} Remaining block content after processing
207
 */
208
Markdown.prototype.loop_re_over_block = function(re, block, cb);
209
```
210

211
**Usage Examples:**
212

213
```javascript
214
var md = new Markdown();
215

216
// Extract all reference definitions
217
var references = [];
218
var remaining = md.loop_re_over_block(
219
  /^\s*\[(.*?)\]:\s*(\S+)/,
220
  "[ref1]: http://example.com\n[ref2]: http://test.com\nOther content",
221
  function(match) {
222
    references.push({ id: match[1], href: match[2] });
223
  }
224
);
225

226
console.log(references); // [{ id: "ref1", href: "http://example.com" }, ...]
227
console.log(remaining);  // "Other content"
228
```
229

230
## Instance Properties
231

232
```javascript { .api }
233
/**
234
 * Markdown instance properties
235
 * @property {Object} dialect - The dialect object containing block and inline rules
236
 * @property {Array} em_state - State tracking for emphasis processing
237
 * @property {Array} strong_state - State tracking for strong emphasis processing
238
 * @property {string} debug_indent - Indentation string for debug output
239
 * @property {Array} tree - Current markdown tree being built (during toTree processing)
240
 */
241
```
242

243
## Advanced Usage Patterns
244

245
### Custom Block Processing
246

247
```javascript
248
var md = new Markdown();
249

250
// Override or extend block processing
251
var originalProcessBlock = md.processBlock;
252
md.processBlock = function(block, next) {
253
  // Custom preprocessing
254
  if (block.match(/^CUSTOM:/)) {
255
    return [["custom_block", {}, block.substr(7)]];
256
  }
257
  
258
  // Fallback to original processing
259
  return originalProcessBlock.call(this, block, next);
260
};
261

262
var tree = md.toTree("CUSTOM: Special content\n\nNormal paragraph");
263
```
264

265
### State Management for Complex Processing
266

267
```javascript
268
var md = new Markdown();
269

270
// Access internal state during processing
271
var originalProcessInline = md.processInline;
272
md.processInline = function(block) {
273
  console.log("Em state:", this.em_state);
274
  console.log("Strong state:", this.strong_state);
275
  return originalProcessInline.call(this, block);
276
};
277

278
var result = md.processInline("**Bold *and italic* text**");
279
```