# toc-md
> Generates a markdown TOC (table of contents)
Latest version **0.2.0** (published 2016-03-20) · 0 weekly downloads
## Install
```sh
npm install toc-md
pnpm add toc-md
yarn add toc-md
bun add toc-md
```
Provides the command `toc-md`.
## Health
**Score 15/100 (F)** — status: abandoned.
Positive: no vulnerabilities.
Warnings: low downloads; no types; no esm support; pre 1.0.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 0.2.0 |
| Published | 2016-03-20 |
| First published | 2014-12-11 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=0.8.0 |
| Dependencies | 8 |
| Known vulnerabilities | 0 (+12 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 5 |
| Author | Evgeniy Gavryushin |
| Maintainers | egavr |
| Keywords | readme, markdown, toc, table of contents |
## Links
- npm: https://www.npmjs.com/package/toc-md
- Repository: https://github.com/eGavr/toc-md
- Issues: https://github.com/eGavr/toc-md/issues
- npm.io page: https://npm.io/package/toc-md
## Dependencies (8)
- [coa](https://npm.io/package/coa.md) 0.4.1
- [colors](https://npm.io/package/colors.md) 1.0.3
- [lodash](https://npm.io/package/lodash.md) 3.0.1
- [marked](https://npm.io/package/marked.md) 0.3.3
- [parse5](https://npm.io/package/parse5.md) 2.1.5
- [vow-fs](https://npm.io/package/vow-fs.md) 0.3.4
- [inherit](https://npm.io/package/inherit.md) 2.2.2
- [vow-node](https://npm.io/package/vow-node.md) 0.2.1
## Alternatives
- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads
## Recent versions
- 0.2.0 (latest) — 2016-03-20
- 0.1.0 — 2015-03-10
- 0.0.3 — 2015-03-03
- 0.0.2 — 2015-02-01
- 0.0.1 — 2014-12-23
- 0.0.1-rc5 — 2014-12-19
- 0.0.1-rc4 — 2014-12-18
- 0.0.1-rc3 — 2014-12-18
- 0.0.1-rc2 — 2014-12-17
- 0.0.1-rc — 2014-12-17
- 0.0.1-alpha5 — 2014-12-15
- 0.0.1-alpha4 — 2014-12-13
- 0.0.1-alpha3 — 2014-12-11
- 0.0.1-alpha2 — 2014-12-11
- 0.0.1-alpha — 2014-12-11
## README
# toc-md [](https://travis-ci.org/eGavr/toc-md) [](https://coveralls.io/r/eGavr/toc-md?branch=master) [](https://david-dm.org/eGavr/toc-md) [](https://david-dm.org/eGavr/toc-md#info=devDependencies)
Generates a markdown TOC (table of contents).
The tool can be used for English and Russian languages.
- [Install](#install)
- [Usage](#usage)
- [API](#api)
- [toc.insert](#tocinsert)
- [toc.clean](#tocclean)
- [Example](#example)
- [CLI](#cli)
- [Insert](#insert)
- [Clean](#clean)
- [Advanced TOC](#advanced-toc)
- [Ignoring of headers](#ignoring-of-headers)
- [Displaying of headers](#displaying-of-headers)
- [Redefinition of anchors](#redefinition-of-anchors)
## Install
```bash
$ npm install toc-md
```
## Usage
Add an HTML comment `` to a markdown file.
A TOC will be generated exactly on this place for the following headers.
### API
```js
var toc = require('toc-md');
```
#### toc.insert
**@param** *{String}* - a source where to insert a TOC (must contain the HTML comment ``)
**@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
```js
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
```bash
$ 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 ) (required)
TARGET : Path to an output markdown file
```
If argument `TARGET` is not specified, a result will be written to `SOURCE`.
#### Example
##### Insert
```bash
$ toc-md path/to/input/markdown path/to/output/markdown --max-depth=4 --bullet='*'
$ toc-md path/to/markdown -m 4 -b '*'
```
##### Clean
```bash
$ 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
`` before a declaration of a header:
```md
# 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
`` before a declaration of a header:
```md
# 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:
```md
# ololo
```
The header `ololo` will refer to the anchor `blah` in a TOC.
---
_Source: https://npm.io/package/toc-md · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._