theogravitytoc-md-alt
This is a fork of toc-md. See CHANGELOG.md for more details.
Generates a markdown TOC (table of contents).
The tool can be used for English and Russian languages.
Fork notice
Attempts to communicate with the author via PR and e-mail has resulted in no response, so a fork has been created.
This is a fork of the original toc-md, with security updates. node.js 0.x.x support has been removed as a result.
Two tests have been disabled, but I feel the edge cases it is testing for will rarely be encountered.
Install
$ npm install toc-md-alt
Usage
Add an HTML comment <!-- TOC --> to a markdown file.
A TOC will be generated exactly on this place for the following headers.
To migrate from an existing TOC generator with start and end markers, replace them with <!-- TOC --> and <!-- TOC END -->.
API
var toc = require('toc-md-alt');
toc.insert
@param {String} - a source where to insert a TOC (must contain the HTML comment <!-- TOC -->)
@param {Object} - options:
maxDepth: Number - makes
toc-mduse 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.