gerhobbelt / marked-toc

Generate a TOC (table of contents) for markdown files.

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

Getting Started

Install the module with npm:

npm i -g marked-toc --save

In any markdown file, add <!-- toc --> where you want to add the TOC. Then in the command line, run:

toc [filename]

If you add the toc to a README.md, no need to add [filename], just run toc.

Usage

var toc = require('marked-toc');
var file = fs.readFileSync('README.md', 'utf8');

// Generate a TOC
toc(file);

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):

var tmpl = '<%= depth %><%= bullet %>[<%= heading %>](#<%= url %>)\n';
toc(file, {template: tmpl});

bullet

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.

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:

toc(file, {clean: ['docs', 'methods']});

converts this:

## docs-foo
Foo

## methods-bar
Bar

to:

* [foo](#docs-foo)
* [bar](#methods-bar)

blacklist

Type: Boolean

Default: true

An array of strings used the omit option:

['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.)

allowedChars

Type: String

Default: -

String of chars that you want to be whitelisted when headings are "slugified" for links, e.g. -_~.

Example:

// This heading
# Getting Started

// Converts to this link
* [Getting Started](#getting-started)

API

Most methods expect a string as the first paramter, so unless otherwise noted, assume that each example gets the str variable from:

var str = fs.readFileSync('README.md', 'utf8')

toc

Generates a Table of Contents from a string.

// Generate a TOC
var table = toc(str);
fs.writeFileSync('toc.md', table);

toc.insert

Inject a TOC at the insertion point in a string, <!-- toc -->.

Params:

• str: the content
• options: object of options

toc.insert(str, options);

toc.add

1. Read a file and inject a TOC at the specified insertion point, <!-- toc -->,
2. Write the file to the specified dest, (or re-write back to the source file if no dest is passed)

toc.add(src, dest, options)

Example:

toc.add('path/to/source.md', 'path/to/dest.md');

Source only:

toc.add('README.md');

toc.raw

Output a "raw" (JSON) Table of Contents object, for customization and usage in templates

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:

{
  // Array of
  "data": [
    {
      "depth": "",
      "bullet": "* ",
      "heading": "Getting Started",
      "url": "getting-started"
    },
    {
      "depth": "",
      "bullet": "* ",
      "heading": "Usage",
      "url": "usage"
    }
  ],

  // String. the actual TOC
  "toc": "* [Getting Started](#getting-started)\n* [Options](#options)\n* [Contributing](#contributing)\n"
}

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

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright (c) 2014 Jon Schlinkert, contributors Licensed under the MIT license.