You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+44-75Lines changed: 44 additions & 75 deletions
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,8 @@
4
4
5
5
## Table of Contents
6
6
7
+
-[Install](#install)
8
+
-[CLI](#cli)
7
9
-[Highlights](#highlights)
8
10
-[Usage](#usage)
9
11
-[API](#api)
@@ -24,24 +26,13 @@
24
26
_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_
25
27
26
28
## Install
29
+
27
30
Install with [npm](https://www.npmjs.com/):
28
31
29
32
```sh
30
33
$ npm install --save markdown-toc
31
34
```
32
35
33
-
Install with [yarn](https://yarnpkg.com):
34
-
35
-
```sh
36
-
$ yarn add markdown-toc
37
-
```
38
-
39
-
## Quick Start
40
-
Assuming you want to add a TOC to README.md:
41
-
1.`$ npm install -g markdown-toc`
42
-
2. Edit README.md and insert the following line where you want the TOC inserted:<br />`<!-- toc -->`
_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_;
44
+
-i: Edit the <input> file directly, injecting the TOC at <!-- toc -->;
71
45
(Without this flag, the default is to print the TOC to stdout.)
72
46
73
47
--json: Print the TOC in JSON format
@@ -91,18 +65,18 @@ _(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](
91
65
92
66
**Features**
93
67
94
-
- Can optionally be used as a [remarkable][] plugin
95
-
- Returns an object with the rendered TOC (on `content`), as well as a `json` property with the raw TOC object, so you can generate your own TOC using templates or however you want
96
-
- Works with [repeated headings](https://gist.github.com/jonschlinkert/ac5d8122bfaaa394f896)
97
-
- Uses sane defaults, so no customization is necessary, but you can if you need to.
98
-
-[filter](#filter-headings) out headings you don't want
99
-
-[Improve](#titleize) the headings you do want
100
-
- Use a custom [slugify](#optionsslugify) function to change how links are created
68
+
* Can optionally be used as a [remarkable](https://github.com/jonschlinkert/remarkable) plugin
69
+
* Returns an object with the rendered TOC (on `content`), as well as a `json` property with the raw TOC object, so you can generate your own TOC using templates or however you want
70
+
* Works with [repeated headings](https://gist.github.com/jonschlinkert/ac5d8122bfaaa394f896)
71
+
* Uses sane defaults, so no customization is necessary, but you can if you need to.
72
+
*[filter](#filter-headings) out headings you don't want
73
+
*[Improve](#titleize) the headings you do want
74
+
* Use a custom [slugify](#optionsslugify) function to change how links are created
101
75
102
76
**Safe!**
103
77
104
-
- Won't mangle markdown in code examples in gfm code blocks that other TOC generators mistake as being actual headings (this happens when markdown headings are show in _examples_, meaning they arent' actually headings that should be in the toc. Also happens with yaml and coffee-script comments, or any comments that use `#`)
105
-
- Won't mangle front-matter, or mistake front-matter properties for headings like other TOC generators
78
+
* Won't mangle markdown in code examples in gfm code blocks that other TOC generators mistake as being actual headings (this happens when markdown headings are show in _examples_, meaning they arent' actually headings that should be in the toc. Also happens with yaml and coffee-script comments, or any comments that use `#`)
79
+
* Won't mangle front-matter, or mistake front-matter properties for headings like other TOC generators
Insert a table of contents immediately after an _opening_`<!-- toc -->` code comment, or replace an existing TOC if both an _opening_ comment and a _closing_ comment (`<!-- tocstop -->`) are found.
144
+
Insert a table of contents immediately after an _opening_`<!-- toc -->` code comment, or replace an existing TOC if both an _opening_ comment and a _closing_ comment (`<!-- tocstop -->`) are found.
171
145
172
146
_(This strategy works well since code comments in markdown are hidden when viewed as HTML, like when viewing a README on GitHub README for example)._
173
147
@@ -209,10 +183,11 @@ As a convenience to folks who wants to create a custom TOC, markdown-toc's inter
209
183
```js
210
184
var toc =require('markdown-toc');
211
185
```
212
-
-`toc.bullets()`: render a bullet list from an array of tokens
213
-
-`toc.linkify()`: linking a heading `content` string
214
-
-`toc.slugify()`: slugify a heading `content` string
215
-
-`toc.strip()`: strip words or characters from a heading `content` string
186
+
187
+
*`toc.bullets()`: render a bullet list from an array of tokens
188
+
*`toc.linkify()`: linking a heading `content` string
189
+
*`toc.slugify()`: slugify a heading `content` string
190
+
*`toc.strip()`: strip words or characters from a heading `content` string
216
191
217
192
**Example**
218
193
@@ -241,15 +216,15 @@ Type: `Function`
241
216
242
217
Default: `undefined`
243
218
244
-
Params:
219
+
Params:
245
220
246
-
-`str`**{String}** the actual heading string
247
-
-`ele`**{Objecct}** object of heading tokens
248
-
-`arr`**{Array}** all of the headings objects
221
+
*`str`**{String}** the actual heading string
222
+
*`ele`**{Objecct}** object of heading tokens
223
+
*`arr`**{Array}** all of the headings objects
249
224
250
225
**Example**
251
226
252
-
From time to time, we might get junk like this in our TOC.
227
+
From time to time, we might get junk like this in our TOC.
253
228
254
229
```
255
230
[.aaa([foo], ...) another bad heading](#-aaa--foo--------another-bad-heading)
@@ -311,23 +286,25 @@ Default: `true`
311
286
Strip extraneous HTML tags from heading text before slugifying. This is similar to GitHub markdown behavior.
312
287
313
288
## About
289
+
314
290
### Related projects
315
-
-[gfm-code-blocks](https://www.npmjs.com/package/gfm-code-blocks): Extract gfm (GitHub Flavored Markdown) fenced code blocks from a string. | [homepage](https://github.com/jonschlinkert/gfm-code-blocks"Extract gfm (GitHub Flavored Markdown) fenced code blocks from a string.")
316
-
-[markdown-link](https://www.npmjs.com/package/markdown-link): Micro util for generating a single markdown link. | [homepage](https://github.com/jonschlinkert/markdown-link"Micro util for generating a single markdown link.")
317
-
-[markdown-utils](https://www.npmjs.com/package/markdown-utils): Micro-utils for creating markdown snippets. | [homepage](https://github.com/jonschlinkert/markdown-utils"Micro-utils for creating markdown snippets.")
318
-
-[pretty-remarkable](https://www.npmjs.com/package/pretty-remarkable): Plugin for prettifying markdown with Remarkable using custom renderer rules. | [homepage](https://github.com/jonschlinkert/pretty-remarkable"Plugin for prettifying markdown with Remarkable using custom renderer rules.")
319
-
-[remarkable](https://www.npmjs.com/package/remarkable): Markdown parser, done right. 100% Commonmark support, extensions, syntax plugins, high speed - all in… [more](https://github.com/jonschlinkert/remarkable) | [homepage](https://github.com/jonschlinkert/remarkable"Markdown parser, done right. 100% Commonmark support, extensions, syntax plugins, high speed - all in one.")
291
+
292
+
*[gfm-code-blocks](https://www.npmjs.com/package/gfm-code-blocks): Extract gfm (GitHub Flavored Markdown) fenced code blocks from a string. | [homepage](https://github.com/jonschlinkert/gfm-code-blocks"Extract gfm (GitHub Flavored Markdown) fenced code blocks from a string.")
293
+
*[markdown-link](https://www.npmjs.com/package/markdown-link): Micro util for generating a single markdown link. | [homepage](https://github.com/jonschlinkert/markdown-link"Micro util for generating a single markdown link.")
294
+
*[markdown-utils](https://www.npmjs.com/package/markdown-utils): Micro-utils for creating markdown snippets. | [homepage](https://github.com/jonschlinkert/markdown-utils"Micro-utils for creating markdown snippets.")
295
+
*[pretty-remarkable](https://www.npmjs.com/package/pretty-remarkable): Plugin for prettifying markdown with Remarkable using custom renderer rules. | [homepage](https://github.com/jonschlinkert/pretty-remarkable"Plugin for prettifying markdown with Remarkable using custom renderer rules.")
296
+
*[remarkable](https://www.npmjs.com/package/remarkable): Markdown parser, done right. 100% Commonmark support, extensions, syntax plugins, high speed - all in… [more](https://github.com/jonschlinkert/remarkable) | [homepage](https://github.com/jonschlinkert/remarkable"Markdown parser, done right. 100% Commonmark support, extensions, syntax plugins, high speed - all in one.")
320
297
321
298
### Contributing
299
+
322
300
Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_
354
330
355
331
To generate the readme, run the following command:
0 commit comments