toc-md

Generates a markdown TOC (table of contents).

The tool can be used for English and Russian languages.

• Install
• Usage
  • API
    • toc.insert
    • toc.clean
    • Example
  • CLI
    • Insert
    • Clean
• Advanced TOC
  • Ignoring of headers
  • Displaying of headers
  • Redefinition of anchors

Install

$ npm install toc-md

Usage

Add an HTML comment <!-- TOC --> to a markdown file.

A TOC will be generated exactly on this place for the following headers.

API

var toc = require('toc-md');

toc.insert

@param {String} - a source where to insert a TOC (must contain the HTML comment <!-- TOC -->)
@param {Object} - options:

• maxDepth: Number - makes toc-md use headings whose depth is at most the specified value (default: 6).

• bullet: Char - the bullet (*, -, +) to use for each element in the generated TOC (default: -).

@param {Function} - callback

toc.clean

@param {String} - a source whereof to clean a TOC
@param {Function} - callback

Example

var fs = require('fs'),
    toc = require('toc-md');
 
var source = fs.readFileSync('markdown-without-toc.md', 'utf-8');
 
var options = {
    maxDepth: 6
};
 
toc.insert(source, options, function (err, res) {
    if (err) {
        console.log(err);
    } else {
        fs.writeFileSync('markdown-with-toc.md', res);
    }
});
 
source = fs.readFileSync('markdown-with-toc.md', 'utf-8');
 
toc.clean(source, function (err, res) {
    if (err) {
        console.log(err);
    } else {
        fs.writeFileSync('markdown-without-toc.md', res);
    }
});

CLI

$ toc-md --help
Generates a markdown TOC (table of contents)
 
Usage:
  toc-md [OPTIONS] [ARGS]
 
Options:
  -h, --help : Help
  -v, --version : Shows the version number
  -m MAXDEPTH, --max-depth=MAXDEPTH : Uses headings whose depth is at most the specified value (default: 6)
  -b BULLET, --bullet=BULLET : The bullet ('*', '-', '+') to use for each element in the generated TOC (default: '-')
  -c, --clean : Cleans a TOC
 
Arguments:
  SOURCE : Path to an input markdown file (it must contain the HTML comment <!-- TOC -->) (required)
  TARGET : Path to an output markdown file

If argument TARGET is not specified, a result will be written to SOURCE.

Example

Insert

$ toc-md path/to/input/markdown path/to/output/markdown --max-depth=4 --bullet='*'
 
$ toc-md path/to/markdown -m 4 -b '*'

Clean

$ toc-md path/to/input/markdown path/to/output/markdown --clean
 
$ toc-md path/to/markdown -c

Advanced TOC

Ignoring of headers

There is an ability to ignore headers in a TOC by adding of the HTML comment
<!-- TOC:ignore --> before a declaration of a header:

<!-- TOC:ignore -->
# ololo

The header ololo will not be displayed in a TOC.

Displaying of headers

There is an ability to change a displaying of a header in a TOC by adding of the HTML comment
<!-- TOC:display:header_text --> before a declaration of a header:

<!-- TOC:display:blah -->
# ololo

The header ololo will be displayed in a TOC as blah.

Redefinition of anchors

There is an ability to redefine an anchor which will be generated for a header by adding of the HTML tag a with attribute name before a declaration of a header:

<a name="blah"></a>
# ololo

The header ololo will refer to the anchor blah in a TOC.