0
# TOC Generation
1

2
Core table of contents generation functionality that processes markdown strings and returns structured TOC data with customizable formatting options.
3

4
## Capabilities
5

6
### Main TOC Function
7

8
Generate a markdown table of contents from markdown content.
9

10
```javascript { .api }
11
/**
12
 * Generate a markdown table of contents from markdown string
13
 * @param {string} str - Markdown content to parse for headings  
14
 * @param {Object} options - Configuration options
15
 * @returns {Object} Result object with content, json, highest, and tokens properties
16
 */
17
function toc(str, options);
18
```
19

20
**Usage Examples:**
21

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

25
// Basic TOC generation
26
const result = toc(`
27
# Introduction
28
Some content here.
29

30
## Getting Started
31
More content.
32

33
### Installation
34
Installation instructions.
35

36
## Usage
37
Usage examples.
38
`);
39

40
console.log(result.content);
41
// Output:
42
// - [Introduction](#introduction)
43
//   - [Getting Started](#getting-started)
44
//     - [Installation](#installation)
45
//   - [Usage](#usage)
46

47
// Access structured data
48
console.log(result.json);
49
// Output: [
50
//   { content: 'Introduction', slug: 'introduction', lvl: 1, i: 0, seen: 0 },
51
//   { content: 'Getting Started', slug: 'getting-started', lvl: 2, i: 1, seen: 0 },
52
//   { content: 'Installation', slug: 'installation', lvl: 3, i: 2, seen: 0 },
53
//   { content: 'Usage', slug: 'usage', lvl: 2, i: 3, seen: 0 }
54
// ]
55
```
56

57
### Result Object Structure
58

59
The TOC function returns a comprehensive result object.
60

61
```javascript { .api }
62
interface TocResult {
63
  /** Generated table of contents markdown */
64
  content: string;
65
  /** Array of heading objects for custom rendering */
66
  json: HeadingObject[];
67
  /** Highest heading level found (used for indentation) */
68
  highest: number;
69
  /** Raw Remarkable tokens from parsing */
70
  tokens: any[];
71
}
72

73
interface HeadingObject {
74
  /** Heading text content */
75
  content: string;
76
  /** URL-safe slug for linking */
77
  slug: string;
78
  /** Heading level (1-6) */
79
  lvl: number;
80
  /** Index in headings array */
81
  i: number;
82
  /** Counter for duplicate headings */
83
  seen: number;
84
}
85
```
86

87
### Configuration Options
88

89
Comprehensive options for customizing TOC generation behavior.
90

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

116
**Usage Examples with Options:**
117

118
```javascript
119
// Limit depth and customize bullets  
120
const result = toc(markdown, {
121
  maxdepth: 3,
122
  bullets: ['-', '*', '+'],
123
  firsth1: false
124
});
125

126
// Custom filtering
127
const result = toc(markdown, {
128
  filter: function(str, ele, arr) {
129
    // Skip headings containing "internal"
130
    return str.indexOf('internal') === -1;
131
  }
132
});
133

134
// Custom slugify function
135
const result = toc(markdown, {
136
  slugify: function(str) {
137
    return str.toLowerCase().replace(/[^\w]/g, '-');
138
  }
139
});
140

141
// Append footer
142
const result = toc(markdown, {
143
  append: '\n\n_(TOC generated automatically)_'
144
});
145
```
146

147
### Duplicate Heading Handling
148

149
Automatic handling of duplicate headings with numbering.
150

151
```javascript
152
const markdown = `
153
# Overview
154
## Setup  
155
## Setup
156
## Setup
157
`;
158

159
const result = toc(markdown);
160
console.log(result.content);
161
// Output:
162
// - [Overview](#overview)
163
//   - [Setup](#setup)
164
//   - [Setup](#setup-1) 
165
//   - [Setup](#setup-2)
166
```
167

168
### Front-matter Support
169

170
Automatic detection and handling of YAML front-matter.
171

172
```javascript
173
const markdown = `
174
---
175
title: My Document
176
author: John Doe
177
---
178

179
# Introduction
180
Content here.
181

182
## Usage
183
More content.
184
`;
185

186
const result = toc(markdown);
187
// Front-matter is ignored, TOC starts from first actual heading
188
```
189

190
### HTML Tag Stripping
191

192
Automatic removal of HTML tags from heading text during slug generation.
193

194
```javascript
195
const markdown = `
196
# <span class="highlight">Important</span> Information
197
## <code>API</code> Reference  
198
`;
199

200
const result = toc(markdown);
201
console.log(result.content);
202
// Output:
203
// - [Important Information](#important-information)
204
//   - [API Reference](#api-reference)
205

206
// Disable tag stripping
207
const result2 = toc(markdown, { stripHeadingTags: false });
208
// Slugs will include HTML tags in processing
209
```