Generate a markdown TOC (table of contents) with Remarkable.
Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your :heart: and support.
(TOC generated by verb using markdown-toc)
Install with npm:
$ npm install --save markdown-toc
Thanks to the following companies, organizations, and individuals for supporting the ongoing maintenance and development of markdown-toc! Become a Sponsor to add your logo to this README, or any of my other projects
https://jaake.tech/ |
Assuming you want to add a TOC to README.md:
$ npm install -g markdown-toc
<!-- toc -->
$ markdown-toc -i README.md
Usage: markdown-toc [options] <input>
input: The Markdown file to parse for table of contents,
or "-" to read from stdin.
-i: Edit the <input> file directly, injecting the TOC at - [Highlights](#highlights)
- [Usage](#usage)
- [API](#api)
* [toc.plugin](#tocplugin)
* [toc.json](#tocjson)
* [toc.insert](#tocinsert)
* [Utility functions](#utility-functions)
- [Options](#options)
* [options.append](#optionsappend)
* [options.filter](#optionsfilter)
* [options.slugify](#optionsslugify)
* [options.bullets](#optionsbullets)
* [options.maxdepth](#optionsmaxdepth)
* [options.firsth1](#optionsfirsth1)
* [options.stripHeadingTags](#optionsstripheadingtags)
- [About](#about)
_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_;
(Without this flag, the default is to print the TOC to stdout.)
--json: Print the TOC in JSON format
--append: Append a string to the end of the TOC
--bullets: Bullets to use for items in the generated TOC
(Supports multiple bullets: --bullets "*" --bullets "-" --bullets "+")
(Default is "*".)
--maxdepth: Use headings whose depth is at most maxdepth
(Default is 6.)
--no-firsth1: Include the first h1-level heading in a file
--no-stripHeadingTags: Do not strip extraneous HTML tags from heading
text before slugifying
--indent: Provide the indentation to use - defaults to ' '
(to specify a tab, use the bash-escaped $'\t')
Features
content
), as well as a json
property with the raw TOC object, so you can generate your own TOC using templates or however you wantSafe!
#
)var toc = require('markdown-toc');
toc('# One\n\n# Two').content;
// Results in:
// - [One](#one)
// - [Two](#two)
To allow customization of the output, an object is returned with the following properties:
content
{String}: The generated table of contents. Unless you want to customize rendering, this is all you need.highest
{Number}: The highest level heading found. This is used to adjust indentation.tokens
{Array}: Headings tokens that can be used for custom renderingUse as a remarkable plugin.
var Remarkable = require('remarkable');
var toc = require('markdown-toc');
function render(str, options) {
return new Remarkable()
.use(toc.plugin(options)) // <= register the plugin
.render(str);
}
Usage example
var results = render('# AAA\n# BBB\n# CCC\nfoo\nbar\nbaz');
Results in:
- [AAA](#aaa)
- [BBB](#bbb)
- [CCC](#ccc)
Object for creating a custom TOC.
toc('# AAA\n## BBB\n### CCC\nfoo').json;
// results in
[ { content: 'AAA', slug: 'aaa', lvl: 1 },
{ content: 'BBB', slug: 'bbb', lvl: 2 },
{ content: 'CCC', slug: 'ccc', lvl: 3 } ]
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.
(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).
Example
<!-- toc -->
- old toc 1
- old toc 2
- old toc 3
<!-- tocstop -->
## abc
This is a b c.
## xyz
This is x y z.
Would result in something like:
<!-- toc -->
- [abc](#abc)
- [xyz](#xyz)
<!-- tocstop -->
## abc
This is a b c.
## xyz
This is x y z.
As a convenience to folks who wants to create a custom TOC, markdown-toc's internal utility methods are exposed:
var toc = require('markdown-toc');
toc.bullets()
: render a bullet list from an array of tokenstoc.linkify()
: linking a heading content
stringtoc.slugify()
: slugify a heading content
stringtoc.strip()
: strip words or characters from a heading content
stringExample
var result = toc('# AAA\n## BBB\n### CCC\nfoo');
var str = '';
result.json.forEach(function(heading) {
str += toc.linkify(heading.content);
});
Append a string to the end of the TOC.
toc(str, {append: '\n_(TOC generated by Verb)_'});
Type: Function
Default: undefined
Params:
str
{String} the actual heading stringele
{Objecct} object of heading tokensarr
{Array} all of the headings objectsExample
From time to time, we might get junk like this in our TOC.
[.aaa([foo], ...) another bad heading](#-aaa--foo--------another-bad-heading)
Unless you like that kind of thing, you might want to filter these bad headings out.
function removeJunk(str, ele, arr) {
return str.indexOf('...') === -1;
}
var result = toc(str, {filter: removeJunk});
//=> beautiful TOC
Type: Function
Default: Basic non-word character replacement.
Example
var str = toc('# Some Article', {slugify: require('uslug')});
Type: String|Array
Default: *
The bullet to use for each item in the generated TOC. If passed as an array (['*', '-', '+']
), the bullet point strings will be used based on the header depth.
Type: Number
Default: 6
Use headings whose depth is at most maxdepth.
Type: Boolean
Default: true
Exclude the first h1-level heading in a file. For example, this prevents the first heading in a README from showing up in the TOC.
Type: Boolean
Default: true
Strip extraneous HTML tags from heading text before slugifying. This is similar to GitHub markdown behavior.
You might also be interested in these projects:
Commits | Contributor |
---|---|
199 | jonschlinkert |
9 | doowb |
4 | dbooth-boston |
3 | sapegin |
3 | Marsup |
2 | dvcrn |
2 | maxogden |
2 | twang2218 |
2 | zeke |
1 | Vortex375 |
1 | chendaniely |
1 | Daniel-Mietchen |
1 | Feder1co5oave |
1 | garygreen |
1 | TehShrike |
1 | citizenmatt |
1 | mgroenhoff |
1 | rafaelsteil |
1 | RichardBradley |
1 | sethvincent |
1 | shanehughes3 |
1 | bcho |
1 | lu22do |
Jon Schlinkert
Copyright © 2023, Jon Schlinkert. Released under the MIT License.
This file was generated by verb-generate-readme, v0.8.0, on July 12, 2023.