Generate a markdown TOC (table of contents).
npm install marked-toc> Generate a TOC (table of contents) for markdown files
_(example)_
* Getting Started
* Usage
* Options
* template
* bullet
* maxDepth
* firsth1
* omit
* clean
* blacklist
* allowedChars
* API
* toc
* toc.insert
* toc.add
* toc.raw
* Contributing
* Author
* License
Install the module with npm:
``bash`
npm i -g marked-toc --save
In any markdown file, add where you want to add the TOC. Then in the command line, run:
`bash`
toc [filename]
If you add the toc to a README.md, no need to add [filename], just run toc.
`javascript
var toc = require('marked-toc');
var file = fs.readFileSync('README.md', 'utf8');
// Generate a TOC
toc(file);
`
All methods accept an object of options as the last argument.
Type: String
Default: <%= depth %><%= bullet %><%= heading %>\n
The Lo-Dash template used to generate the Table of Contents.
Example (this is the default):
`js`
var tmpl = '<%= depth %><%= bullet %><%= heading %>\n';
toc(file, {template: tmpl});
Type: String|Array
Default: *
The bullet to use for each item in the generated TOC. This is passed as a variable to the <%= bullet %> template.
If an array, like ['* ', '- '], 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: False
Include the first h1-level heading in a file. For example, this prevent the first heading in a README from showing up in the TOC.
Type: Array
Default: ['Table of Contents', 'TOC', 'TABLE OF CONTENTS']
Omit entire headings from the TOC if they have these strings.
Type: Array
Default: ['mixin', 'helper', 'filter']
Strip "blacklisted" keywords from the headings.
Example:
`js`
toc(file, {clean: ['docs', 'methods']});
converts this:
`markdowndocs-foo
Foo
`
to:
`
Type: Boolean
Default: true
An array of strings used the omit option:
`js`
['grunt', 'helper', 'handlebars-helper', 'mixin', 'filter', 'assemble-contrib', 'assemble']
_(These strings are used a lot in documentation headings, but (usually) shouldn't show up in the gererated TOC.)_
Type: String
Default: -
String of chars that you want to be whitelisted when headings are "slugified" for links, e.g. -_~.
Example:
`markdown
// This headingGetting Started
// Converts to this link
* Getting Started
`
Most methods expect a string as the first paramter, so unless otherwise noted, assume that each example gets the str variable from:
`js`
var str = fs.readFileSync('README.md', 'utf8')
Generates a Table of Contents from a string.
`js`
// Generate a TOC
var table = toc(str);
fs.writeFileSync('toc.md', table);
Inject a TOC at the insertion point in a string, .
Params:
* str: the contentoptions
* : object of options
`js`
toc.insert(str, options);
1. Read a file and inject a TOC at the specified insertion point, ,dest
2. Write the file to the specified , _(or re-write back to the source file if no dest is passed)_
`js`
toc.add(src, dest, options)
Example:
`js`
toc.add('path/to/source.md', 'path/to/dest.md');
Source only:
`js`
toc.add('README.md');
Output a "raw" (JSON) Table of Contents object, for customization and usage in templates
`js`
toc.raw(str, options);
Returns an object (JSON) with two properties, data and toc:
* data: array of headings and associated properties used to construct a TOC. TIP: this can be extended with properties, such as src path etc.toc
* : the actual Table of Contents result, as a string
Example:
`json
{
// Array of
"data": [
{
"depth": "",
"bullet": "* ",
"heading": "Getting Started",
"url": "getting-started"
},
{
"depth": "",
"bullet": "* ",
"heading": "Usage",
"url": "usage"
}
],
// String. the actual TOC
"toc": " Getting Started\n Options\n* Contributing\n"
}
`
See an example.
+ github/jonschlinkert
+ twitter/jonschlinkert