0
# TOC Insertion
1
2
Insert table of contents into existing markdown files using HTML comment markers. This functionality allows for automatic TOC management within markdown documents.
3
4
## Capabilities
5
6
### Insert Function
7
8
Insert or replace TOC content between HTML comment markers in markdown.
9
10
```javascript { .api }
11
/**
12
* Insert TOC into markdown content between comment markers
13
* @param {string} str - Markdown content with TOC markers
14
* @param {Object} options - Configuration options
15
* @returns {string} Markdown with TOC inserted or replaced
16
*/
17
function insert(str, options);
18
```
19
20
**Usage Examples:**
21
22
```javascript
23
const toc = require('markdown-toc');
24
25
// Basic insertion
26
const markdown = `
27
# My Document
28
29
<!-- toc -->
30
<!-- tocstop -->
31
32
## Chapter 1
33
Content for chapter 1.
34
35
## Chapter 2
36
Content for chapter 2.
37
`;
38
39
const result = toc.insert(markdown);
40
console.log(result);
41
// Output:
42
// # My Document
43
//
44
// <!-- toc -->
45
//
46
// - [Chapter 1](#chapter-1)
47
// - [Chapter 2](#chapter-2)
48
//
49
// <!-- tocstop -->
50
//
51
// ## Chapter 1
52
// Content for chapter 1.
53
//
54
// ## Chapter 2
55
// Content for chapter 2.
56
```
57
58
### TOC Markers
59
60
The insertion system uses HTML comment markers to identify where to place the TOC.
61
62
**Standard Markers:**
63
- `<!-- toc -->` - Opening marker where TOC should be inserted
64
- `<!-- tocstop -->` - Closing marker (optional, for replacement)
65
66
**Single Marker Behavior:**
67
If only `<!-- toc -->` is present, the TOC is inserted after it.
68
69
**Dual Marker Behavior:**
70
If both `<!-- toc -->` and `<!-- tocstop -->` are present, any content between them is replaced with the new TOC.
71
72
```javascript
73
// Replace existing TOC
74
const markdown = `
75
<!-- toc -->
76
- old toc item 1
77
- old toc item 2
78
<!-- tocstop -->
79
80
# New Heading
81
Content here.
82
`;
83
84
const result = toc.insert(markdown);
85
// Old TOC content is completely replaced
86
```
87
88
### Configuration Options
89
90
Customize insertion behavior and TOC generation.
91
92
```javascript { .api }
93
interface InsertOptions extends TocOptions {
94
/** Regex for TOC markers (default: /(?:<!-- toc(?:\s*stop)? -->)/g) */
95
regex?: RegExp;
96
/** Opening TOC marker (default: '<!-- toc -->\n\n') */
97
open?: string;
98
/** Closing TOC marker (default: '<!-- tocstop -->') */
99
close?: string;
100
/** Pre-generated TOC content to use instead of generating */
101
toc?: string;
102
}
103
```
104
105
**Usage Examples with Options:**
106
107
```javascript
108
// Custom markers
109
const result = toc.insert(markdown, {
110
open: '<!-- TABLE OF CONTENTS -->\n',
111
close: '<!-- END TOC -->',
112
regex: /(?:<!-- TABLE OF CONTENTS(?:\s*END TOC)? -->)/g
113
});
114
115
// Pre-generated TOC content
116
const customToc = '- [Overview](#overview)\n- [Details](#details)';
117
const result = toc.insert(markdown, {
118
toc: customToc
119
});
120
121
// Combined with TOC generation options
122
const result = toc.insert(markdown, {
123
maxdepth: 2,
124
bullets: '-',
125
append: '\n_(Auto-generated)_'
126
});
127
```
128
129
### Front-matter Handling
130
131
Automatic preservation of YAML front-matter during insertion.
132
133
```javascript
134
const markdown = `
135
---
136
title: Documentation
137
layout: page
138
---
139
140
# Introduction
141
142
<!-- toc -->
143
<!-- tocstop -->
144
145
## Getting Started
146
Content here.
147
`;
148
149
const result = toc.insert(markdown);
150
// Front-matter is preserved at the top of the document
151
// TOC is generated only from content after front-matter
152
```
153
154
### Error Handling
155
156
The insertion function includes validation for marker usage.
157
158
```javascript
159
// Multiple TOC sections not allowed
160
const invalidMarkdown = `
161
<!-- toc -->
162
<!-- tocstop -->
163
164
## Section 1
165
166
<!-- toc -->
167
<!-- tocstop -->
168
169
## Section 2
170
`;
171
172
try {
173
toc.insert(invalidMarkdown);
174
} catch (error) {
175
console.log(error.message);
176
// "markdown-toc only supports one Table of Contents per file."
177
}
178
```
179
180
### Integration with File Processing
181
182
Common pattern for processing markdown files.
183
184
```javascript
185
const fs = require('fs');
186
const toc = require('markdown-toc');
187
188
// Read file, insert TOC, write back
189
const filePath = 'README.md';
190
const content = fs.readFileSync(filePath, 'utf8');
191
const updated = toc.insert(content, {
192
maxdepth: 3,
193
bullets: '*'
194
});
195
fs.writeFileSync(filePath, updated);
196
```
197
198
### Whitespace Preservation
199
200
The insertion function preserves trailing whitespace and newlines from the original document.
201
202
```javascript
203
const markdown = 'Content here.\n\n<!-- toc -->\n\n## Heading\n\n\n';
204
const result = toc.insert(markdown);
205
// Original trailing whitespace is maintained
206
```