Generate a markdown TOC (table of contents) with Remarkable.
(TOC generated by verb using markdown-toc)
Install with npm:
$ npm install --save markdown-toc
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 <!-- 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
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: