Generate a markdown TOC (table of contents) with Remarkable.
- Won't mangle markdown in code examples (like headings, coffee or yaml comments in gfm fenced code blocks that other TOC generators mistake as being actual 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- gfm-code-blocks: Extract gfm (GitHub Flavored Markdown) fenced code blocks from a string.
- markdown-utils: Micro-utils for creating markdown snippets.
- markdown-link: Micro util for generating a single markdown link.
- pretty-remarkable: Plugin for prettifying markdown with Remarkable using custom renderer rules.
- remarkable: Markdown parser, done right. 100% Commonmark support, extensions, syntax plugins, high speed - all in… more
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 headingcontentstringtoc.slugify(): slugify a headingcontentstringtoc.strip(): strip words or characters from a headingcontentstring
Example
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 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 removeJunk(str, ele, arr) {
return str.indexOf('...') === -1;
}
var result = toc(str, {filter: removeJunk});
//=> beautiful TOCType: 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 testPull requests and stars are always welcome. For bugs and feature requests, please create an issue
Jon Schlinkert
Copyright © 2014-2015 Jon Schlinkert Released under the MIT license.
This file was generated by verb-cli on June 25, 2015.