markdown-toc
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
npm
Install withnpm i markdown-toc --save
Related projects
- remarkable: Markdown parser, done right. 100% Commonmark support, extensions, syntax plugins, high speed - all in one.
- markdown-utils: Micro-utils for creating markdown snippets.
- markdown-link: Micro util for generating a single markdown link.
- gfm-code-blocks: Extract gfm (GitHub Flavored Markdown) fenced code blocks from a string.
Usage
var toc = ; 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
API
toc.json
Object for creating a custom TOC.
json; // results in content: 'AAA' lvl: 1 content: 'BBB' lvl: 2 content: 'CCC' lvl: 3
toc.insert
Insert a table of contents immediately after an opening `
code comment, or replace an existing TOC if both an _opening_ comment and a _closing_ comment (
`) 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
- old toc 1- old toc 2- old toc 3 ## abcThis is a b c. ## xyzThis is x y z.
Would result in something like:
- [abc](#abc)- [xyz](#xyz) ## abcThis is a b c. ## xyzThis is x y z.
Utility functions
As a convenience to folks who wants to create a custom TOC, markdown-toc's internal utility methods are exposed:
var 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 = ;var str = ''; resultjson;
Options
options.append
Append a string to the end of the TOC.
;
options.filter
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.
{ return str === -1;} var result = ;//=> 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.
options.bullets
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.
options.maxDepth
Type: Number
Default: 3
Use headings whose depth is at most maxDepth.
options.firsth1
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.
Running tests
Install dev dependencies.
npm i -d && npm test
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue
Author
Jon Schlinkert
License
Copyright (c) 2014-2015 Jon Schlinkert
Released under the MIT license
This file was generated by verb-cli on March 25, 2015.