Generate a markdown TOC (table of contents) with Remarkable.
- Won't mangle markdown in code examples (like headings in gfm fenced code blocks that other TOC generators mistake as being real headings)
- Uses sane defaults, so no customization is necessary, but you can if you need to.
- Get JSON to generate your own TOC from whatever templates you want to use
- filter out headings you don't want
- Improve the headings you do want
Install with npm
npm i markdown-toc --save
- remarkable: Markdown parser, done right. 100% Commonmark support, extensions, syntax plugins, high speed - all in one.
- markdown-utils: Micro-utils for creating markdown snippets.
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 rendering
Object for creating a custom TOC.
toc('# AAA\n## BBB\n### CCC\nfoo').json;
// results in
[ { content: 'AAA', lvl: 1 },
{ content: 'BBB', lvl: 2 },
{ content: '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 headingcontent
stringtoc.slugify()
: slugify a headingcontent
stringtoc.strip()
: strip words or characters from a headingcontent
string
Example
var result = toc('# AAA\n## BBB\n### CCC\nfoo');
var str = '';
result.json.forEach(function(heading) {
str += toc.linkify(heading.content);
});
Type: Function
Default: undefined
Params:
str
{String} the actual heading stringele
{Objecct} object of heading tokensarr
{Array} all of the headings objects
Example
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 removeYunk(str, ele, arr) {
return str.indexOf('...') === -1;
}
var result = toc(str, {filter: removeYunk});
//=> beautiful TOC, sans "Yunk"? wtf is "Yunk"
// anyway? Look, j and y are kind of sort of
// close on the keyboard. Regardless, it gets the
// yunk out of your headings.
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: 3
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.
Install dev dependencies.
npm i -d && npm test
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue
Jon Schlinkert
Copyright (c) 2014-2015 Jon Schlinkert
Released under the MIT license
This file was generated by verb-cli on March 14, 2015.