0
# Markdown TOC
1

2
Markdown TOC is a JavaScript library that generates table of contents (TOC) for Markdown documents using the Remarkable parser. It provides both a programmatic API and command-line interface for creating navigable table of contents with customizable formatting, depth limits, and filtering capabilities.
3

4
## Package Information
5

6
- **Package Name**: markdown-toc
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install markdown-toc`
10

11
## Core Imports
12

13
```javascript
14
const toc = require('markdown-toc');
15
```
16

17
For ES modules:
18

19
```javascript
20
import toc from 'markdown-toc';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const toc = require('markdown-toc');
27

28
// Generate TOC from markdown string
29
const result = toc('# One\n\n## Two\n\n### Three');
30
console.log(result.content);
31
// Output:
32
// - [One](#one)
33
//   - [Two](#two)
34
//     - [Three](#three)
35

36
// Access structured data
37
console.log(result.json);
38
// Output: [
39
//   { content: 'One', slug: 'one', lvl: 1 },
40
//   { content: 'Two', slug: 'two', lvl: 2 },
41
//   { content: 'Three', slug: 'three', lvl: 3 }
42
// ]
43
```
44

45
## Architecture
46

47
Markdown TOC is built around several key components:
48

49
- **Core TOC Generator**: Main `toc()` function that processes markdown and returns structured TOC data
50
- **Remarkable Integration**: Plugin interface for using with Remarkable markdown parser instances
51
- **CLI Interface**: Command-line tool for file processing and TOC injection
52
- **Insertion System**: Functionality to inject TOCs into existing markdown files between HTML comments
53
- **Utility Functions**: Helper functions for slugification, linking, and text processing
54

55
## Capabilities
56

57
### TOC Generation
58

59
Core table of contents generation from markdown strings with full control over formatting and structure.
60

61
```javascript { .api }
62
/**
63
 * Generate a markdown table of contents from markdown string
64
 * @param {string} str - Markdown content to parse for headings
65
 * @param {Object} options - Configuration options
66
 * @returns {Object} Result object with content, json, highest, and tokens properties
67
 */
68
function toc(str, options);
69

70
interface TocResult {
71
  /** Generated table of contents markdown */
72
  content: string;
73
  /** Array of heading objects for custom rendering */
74
  json: HeadingObject[];
75
  /** Highest heading level found (used for indentation) */
76
  highest: number;
77
  /** Raw Remarkable tokens */
78
  tokens: any[];
79
}
80

81
interface HeadingObject {
82
  /** Heading text content */
83
  content: string;
84
  /** URL-safe slug for linking */
85
  slug: string;
86
  /** Heading level (1-6) */
87
  lvl: number;
88
  /** Index in headings array */
89
  i: number;
90
  /** Counter for duplicate headings */
91
  seen: number;
92
}
93
```
94

95
[TOC Generation](./toc-generation.md)
96

97
### JSON Data Access
98

99
Access structured heading data from TOC generation results for custom rendering.
100

101
```javascript { .api }
102
// Access json property on toc() result
103
const result = toc(markdown);
104
const headingData = result.json; // Array of HeadingObject
105
```
106

107
The `json` property contains the same `HeadingObject[]` structure as documented in TOC Generation.
108

109
### TOC Insertion
110

111
Insert table of contents into existing markdown files using HTML comment markers.
112

113
```javascript { .api }
114
/**
115
 * Insert TOC into markdown content between comment markers
116
 * @param {string} str - Markdown content with TOC markers
117
 * @param {Object} options - Configuration options
118
 * @returns {string} Markdown with TOC inserted or replaced
119
 */
120
function insert(str, options);
121
```
122

123
[TOC Insertion](./toc-insertion.md)
124

125
### Remarkable Plugin
126

127
Use as a plugin with Remarkable markdown parser instances for integrated TOC generation.
128

129
```javascript { .api }
130
/**
131
 * Create Remarkable plugin for TOC generation
132
 * @param {Object} options - Plugin configuration options
133
 * @returns {Function} Plugin function for Remarkable.use()
134
 */
135
function plugin(options);
136
```
137

138
[Remarkable Plugin](./remarkable-plugin.md)
139

140
### Utility Functions
141

142
Helper functions for custom TOC rendering and text processing.
143

144
```javascript { .api }
145
/**
146
 * Generate URL-safe slug from heading text
147
 * @param {string} str - Text to slugify
148
 * @param {Object} options - Slugify options
149
 * @returns {string} URL-safe slug
150
 */
151
function slugify(str, options);
152

153
/**
154
 * Convert heading into markdown link
155
 * @param {Object} token - Heading token object
156
 * @param {Object} options - Linking options
157
 * @returns {Object} Token with linkified content
158
 */
159
function linkify(token, options);
160

161
/**
162
 * Render bullet list from heading tokens
163
 * @param {Array} tokens - Array of heading tokens
164
 * @param {Object} options - Bullet formatting options
165
 * @returns {string} Formatted bullet list markdown
166
 */
167
function bullets(tokens, options);
168

169
/**
170
 * Process and clean heading text for display
171
 * @param {string} str - Heading text to process
172
 * @param {Object} options - Processing options
173
 * @returns {string} Cleaned heading text
174
 */
175
function titleize(str, options);
176

177
/**
178
 * Strip specified words or characters from heading text
179
 * @param {string} str - Text to process
180
 * @param {Object} options - Strip configuration
181
 * @returns {string} Processed text
182
 */
183
function strip(str, options);
184
```
185

186
[Utility Functions](./utility-functions.md)
187

188
### Command Line Interface
189

190
Command-line tool for processing markdown files and generating TOCs.
191

192
```bash
193
# Basic TOC generation
194
markdown-toc README.md
195

196
# Inject TOC into file
197
markdown-toc -i README.md
198

199
# Generate JSON output
200
markdown-toc --json README.md
201

202
# Custom options
203
markdown-toc --maxdepth 3 --bullets "*" --append "_(Generated by markdown-toc)_" README.md
204
```
205

206
[Command Line Interface](./cli.md)
207

208
## Types
209

210
```javascript { .api }
211
interface TocOptions {
212
  /** Exclude first H1 heading (default: true) */
213
  firsth1?: boolean;
214
  /** Maximum heading depth to include (default: 6) */
215
  maxdepth?: number;
216
  /** Bullet characters for list items (default: '*') */
217
  bullets?: string | string[];
218
  /** Text to append to end of TOC */
219
  append?: string;
220
  /** Enable/customize linking (default: true) */
221
  linkify?: boolean | Function;
222
  /** Strip HTML tags from headings (default: true) */
223
  stripHeadingTags?: boolean;
224
  /** Filter function for headings */
225
  filter?: (str: string, element: Object, arr: Array) => boolean;
226
  /** Custom slugify function */
227
  slugify?: Function | boolean;
228
  /** Custom titleize function */
229
  titleize?: Function | boolean;
230
  /** Text stripping configuration */
231
  strip?: Function | Array | string;
232
}
233

234
interface InsertOptions extends TocOptions {
235
  /** Regex for TOC markers */
236
  regex?: RegExp;
237
  /** Opening TOC marker */
238
  open?: string;
239
  /** Closing TOC marker */
240
  close?: string;
241
  /** Pre-generated TOC content */
242
  toc?: string;
243
}
244
```