marked-toc
Generate a TOC (table of contents) for markdown files
(example)
Getting Started
Install the module with npm:
In any markdown file, add <!-- toc -->
where you want to add the TOC. Then in the command line, run:
If you add the toc to a README.md
, no need to add [filename]
, just run toc
.
Usage
Options
All methods accept an object of options as the last argument.
template
Type: String
Default: <%= depth %><%= bullet %>[<%= heading %>](#<%= url %>)\n
The Lo-Dash template used to generate the Table of Contents.
Example (this is the default):
bullet
Type: String
Default: *
The bullet to use for each item in the generated TOC. This is passed as a variable to the <%= bullet %>
template.
maxDepth
Type: Number
Default: 3
Use headings whose depth is at most maxDepth.
firsth1
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.
omit
Type: Array
Default: ['Table of Contents', 'TOC', 'TABLE OF CONTENTS']
Omit entire headings from the TOC if they have these strings.
clean
Type: Array
Default: ['mixin', 'helper', 'filter']
Strip "blacklisted" keywords from the headings.
Example:
converts this:
to:
blacklist
Type: Boolean
Default: true
An array of strings used the omit
option:
(These strings are used a lot in documentation headings, but (usually) shouldn't show up in the gererated TOC.)
allowedChars
Type: String
Default: -
String of chars that you want to be whitelisted when headings are "slugified" for links, e.g. -_~
.
Example:
API
Most methods expect a string as the first paramter, so unless otherwise noted, assume that each example gets the str
variable from:
toc
Generates a Table of Contents from a string.
toc.insert
Inject a TOC at the insertion point in a string, <!-- toc -->
.
Params:
str
: the contentoptions
: object of options
toc.add
Read a file and inject a TOC at the specified insertion point,
<!-- toc -->
,Write the file to the specified
dest
, (or re-write back to the source file if nodest
is passed)
Example:
Source only:
toc.raw
Output a "raw" (JSON) Table of Contents object, for customization and usage in templates
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:
See an example.
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint your code using jshint and run tests with mocha -R spec
before making a pull request.
Author
License
Copyright (c) 2014 Jon Schlinkert, contributors Licensed under the MIT license.
Last updated