0
# Remarkable Plugin
1

2
Use markdown-toc as a plugin with Remarkable markdown parser instances for integrated TOC generation during markdown rendering.
3

4
## Capabilities
5

6
### Plugin Function
7

8
Create a Remarkable plugin for TOC generation that integrates with the parser's rendering pipeline.
9

10
```javascript { .api }
11
/**
12
 * Create Remarkable plugin for TOC generation
13
 * @param {Object} options - Plugin configuration options
14
 * @returns {Function} Plugin function for use with Remarkable.use()
15
 */
16
function plugin(options);
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
const Remarkable = require('remarkable');
23
const toc = require('markdown-toc');
24

25
// Basic plugin usage
26
function render(str, options) {
27
  return new Remarkable()
28
    .use(toc.plugin(options))
29
    .render(str);
30
}
31

32
const result = render(`
33
# Overview
34
Content here.
35

36
## Getting Started  
37
Setup instructions.
38

39
## Usage
40
Usage examples.
41
`);
42

43
console.log(result.content);
44
// Output:
45
// - [Overview](#overview)
46
//   - [Getting Started](#getting-started)
47
//   - [Usage](#usage)
48
```
49

50
### Plugin Integration
51

52
The plugin integrates directly with Remarkable's rendering system.
53

54
```javascript
55
const Remarkable = require('remarkable');
56
const toc = require('markdown-toc');
57

58
// Create parser instance with TOC plugin
59
const md = new Remarkable({
60
  html: true,
61
  linkify: true
62
}).use(toc.plugin({
63
  maxdepth: 3,
64
  bullets: ['-', '*', '+']
65
}));
66

67
// Render markdown with integrated TOC generation
68
const markdown = `
69
# Documentation
70

71
## API Reference
72
API details here.
73

74
### Methods
75
Method documentation.
76

77
## Examples
78
Example usage.
79
`;
80

81
const result = md.render(markdown);
82
// Returns TOC result object with content, json, highest, tokens
83
```
84

85
### Plugin Options
86

87
All standard TOC options are available for the plugin.
88

89
```javascript { .api }
90
interface PluginOptions extends TocOptions {
91
  /** Exclude first H1 heading (default: true) */
92
  firsth1?: boolean;
93
  /** Maximum heading depth to include (default: 6) */
94
  maxdepth?: number;
95
  /** Bullet characters for list items */
96
  bullets?: string | string[];
97
  /** Text to append to end of TOC */
98
  append?: string;
99
  /** Enable/customize linking (default: true) */
100
  linkify?: boolean | Function;
101
  /** Strip HTML tags from headings (default: true) */
102
  stripHeadingTags?: boolean;
103
  /** Filter function for headings */
104
  filter?: (str: string, element: Object, arr: Array) => boolean;
105
  /** Custom slugify function */
106
  slugify?: Function | boolean;
107
  /** Custom titleize function */
108
  titleize?: Function | boolean;
109
  /** Text stripping configuration */
110
  strip?: Function | Array | string;
111
}
112
```
113

114
**Usage Examples with Options:**
115

116
```javascript
117
const md = new Remarkable()
118
  .use(toc.plugin({
119
    maxdepth: 2,
120
    firsth1: false,
121
    bullets: '*',
122
    filter: function(str, ele, arr) {
123
      return str.indexOf('private') === -1;
124
    }
125
  }));
126

127
// Custom slugify function
128
const md2 = new Remarkable()
129
  .use(toc.plugin({
130
    slugify: function(str) {
131
      return str.toLowerCase()
132
        .replace(/[^\w\s-]/g, '')
133
        .replace(/\s+/g, '-');
134
    }
135
  }));
136
```
137

138
### Renderer Override
139

140
The plugin works by overriding Remarkable's renderer to capture heading information.
141

142
```javascript
143
// The plugin modifies the renderer behavior
144
const md = new Remarkable()
145
  .use(toc.plugin());
146

147
// During rendering, the plugin:
148
// 1. Captures all heading tokens
149
// 2. Processes them for TOC generation  
150
// 3. Returns structured TOC data instead of HTML
151
```
152

153
### Integration with Other Plugins
154

155
The TOC plugin can be combined with other Remarkable plugins.
156

157
```javascript
158
const Remarkable = require('remarkable');
159
const toc = require('markdown-toc');
160

161
const md = new Remarkable()
162
  .use(require('remarkable-emoji'))  // Add emoji support
163
  .use(toc.plugin({                 // Add TOC generation
164
    maxdepth: 3
165
  }))
166
  .use(require('remarkable-attrs')); // Add attribute support
167

168
const result = md.render('# Hello :smile:\n## Section {.highlight}');
169
```
170

171
### TOC Comment Processing
172

173
The plugin automatically detects and processes TOC comment markers.
174

175
```javascript
176
const markdown = `
177
# Introduction
178
Some content.
179

180
<!-- toc -->
181

182
## Getting Started
183
Content here.
184

185
## Advanced Usage  
186
More content.
187
`;
188

189
const md = new Remarkable().use(toc.plugin());
190
const result = md.render(markdown);
191

192
// TOC is generated starting from headings after the <!-- toc --> marker
193
// Headings before the marker are excluded from TOC
194
```
195

196
### Result Processing
197

198
The plugin returns the same result structure as the main TOC function.
199

200
```javascript
201
const md = new Remarkable().use(toc.plugin());
202
const result = md.render(markdown);
203

204
// Access generated TOC content
205
console.log(result.content);
206

207
// Access structured heading data
208
console.log(result.json);
209

210
// Access metadata
211
console.log(result.highest); // Highest heading level
212
console.log(result.tokens);  // Raw Remarkable tokens
213
```
214

215
### Custom Rendering
216

217
Use the plugin's structured output for custom TOC rendering.
218

219
```javascript
220
const md = new Remarkable().use(toc.plugin());
221
const result = md.render(markdown);
222

223
// Custom TOC rendering
224
const customToc = result.json
225
  .map(heading => {
226
    const indent = '  '.repeat(heading.lvl - result.highest);
227
    return `${indent}${heading.lvl}. [${heading.content}](#${heading.slug})`;
228
  })
229
  .join('\n');
230

231
console.log(customToc);
232
// Output numbered list instead of bullets
233
```