1.0.1 • Published 8 years agoCLI

markdown-toc-unlazy

Licence

MIT

Version

1.0.1

Deps

Size

27 kB

Vulns

Weekly

Stars

1.8K

Summary Dependency Versions

markdown-toc

Generate a markdown TOC (table of contents) with Remarkable.

Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your and support.

Highlights
Usage
API
Options
About

(TOC generated by verb using markdown-toc)

Install

Install with npm:

$ npm install --save markdown-toc

Thanks to the following companies, organizations, and individuals for supporting the ongoing maintenance and development of markdown-toc! Become a Sponsor to add your logo to this README, or any of my other projects

Gold Sponsors


https://jaake.tech/

Quick Start

Assuming you want to add a TOC to README.md:

$ npm install -g markdown-toc
Edit README.md and insert the following line where you want the TOC inserted:

$ markdown-toc -i README.md

CLI

Usage: markdown-toc [options] <input>

  input:        The Markdown file to parse for table of contents,
                or "-" to read from stdin.

  -i:           Edit the <input> file directly, injecting the TOC at - [Highlights](#highlights)
- [Usage](#usage)
- [API](#api)
  * [toc.plugin](#tocplugin)
  * [toc.json](#tocjson)
  * [toc.insert](#tocinsert)
  * [Utility functions](#utility-functions)
- [Options](#options)
  * [options.append](#optionsappend)
  * [options.filter](#optionsfilter)
  * [options.slugify](#optionsslugify)
  * [options.bullets](#optionsbullets)
  * [options.maxdepth](#optionsmaxdepth)
  * [options.firsth1](#optionsfirsth1)
  * [options.stripHeadingTags](#optionsstripheadingtags)
- [About](#about)

_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_;
                (Without this flag, the default is to print the TOC to stdout.)

  --json:       Print the TOC in JSON format

  --append:     Append a string to the end of the TOC

  --bullets:    Bullets to use for items in the generated TOC
                (Supports multiple bullets: --bullets "*" --bullets "-" --bullets "+")
                (Default is "*".)

  --maxdepth:   Use headings whose depth is at most maxdepth
                (Default is 6.)

  --no-firsth1: Include the first h1-level heading in a file

  --no-stripHeadingTags: Do not strip extraneous HTML tags from heading
                         text before slugifying

  --indent:     Provide the indentation to use - defaults to '  '
                (to specify a tab, use the bash-escaped 
Highlights
Features

Can optionally be used as a remarkable plugin
Returns an object with the rendered TOC (on content), as well as a json property with the raw TOC object, so you can generate your own TOC using templates or however you want
Works with repeated headings
Uses sane defaults, so no customization is necessary, but you can if you need to.
filter out headings you don't want
Improve the headings you do want
Use a custom slugify function to change how links are created

Safe!

Won't mangle markdown in code examples in gfm code blocks that other TOC generators mistake as being actual headings (this happens when markdown headings are show in examples, meaning they arent' actually headings that should be in the toc. Also happens with yaml and coffee-script comments, or any comments that use #)
Won't mangle front-matter, or mistake front-matter properties for headings like other TOC generators

Usage
var toc = require('markdown-toc');

toc('# One\n\n# Two').content;
// Results in:
// - [One](#one)
// - [Two](#two)
To allow customization of the output, an object is returned with the following properties:

content {String}: The generated table of contents. Unless you want to customize rendering, this is all you need.
highest {Number}: The highest level heading found. This is used to adjust indentation.
tokens {Array}: Headings tokens that can be used for custom rendering

API
toc.plugin
Use as a remarkable plugin.
var Remarkable = require('remarkable');
var toc = require('markdown-toc');

function render(str, options) {
  return new Remarkable()
    .use(toc.plugin(options)) // <= register the plugin
    .render(str);
}
Usage example
var results = render('# AAA\n# BBB\n# CCC\nfoo\nbar\nbaz');
Results in:
- [AAA](#aaa)
- [BBB](#bbb)
- [CCC](#ccc)
toc.json
Object for creating a custom TOC.
toc('# AAA\n## BBB\n### CCC\nfoo').json;

// results in
[ { content: 'AAA', slug: 'aaa', lvl: 1 },
  { content: 'BBB', slug: 'bbb', lvl: 2 },
  { content: 'CCC', slug: 'ccc', lvl: 3 } ]
toc.insert
Insert a table of contents immediately after an opening <!-- toc --> code comment, or replace an existing TOC if both an opening comment and a closing comment (<!-- tocstop -->) are found.
(This strategy works well since code comments in markdown are hidden when viewed as HTML, like when viewing a README on GitHub README for example).
Example
<!-- toc -->
- old toc 1
- old toc 2
- old toc 3
<!-- tocstop -->

## abc
This is a b c.

## xyz
This is x y z.
Would result in something like:
<!-- toc -->
- [abc](#abc)
- [xyz](#xyz)
<!-- tocstop -->

## abc
This is a b c.

## xyz
This is x y z.
Utility functions
As a convenience to folks who wants to create a custom TOC, markdown-toc's internal utility methods are exposed:
var toc = require('markdown-toc');

toc.bullets(): render a bullet list from an array of tokens
toc.linkify(): linking a heading content string
toc.slugify(): slugify a heading content string
toc.strip(): strip words or characters from a heading content string

Example
var result = toc('# AAA\n## BBB\n### CCC\nfoo');
var str = '';

result.json.forEach(function(heading) {
  str += toc.linkify(heading.content);
});
Options
options.append
Append a string to the end of the TOC.
toc(str, {append: '\n_(TOC generated by Verb)_'});
options.filter
Type: Function
Default: undefined
Params:

str {String} the actual heading string
ele {Objecct} object of heading tokens
arr {Array} all of the headings objects

Example
From time to time, we might get junk like this in our TOC.
[.aaa([foo], ...) another bad heading](#-aaa--foo--------another-bad-heading)
Unless you like that kind of thing, you might want to filter these bad headings out.
function removeJunk(str, ele, arr) {
  return str.indexOf('...') === -1;
}

var result = toc(str, {filter: removeJunk});
//=> beautiful TOC
options.slugify
Type: Function
Default: Basic non-word character replacement.
Example
var str = toc('# Some Article', {slugify: require('uslug')});
options.bullets
Type: String|Array
Default: *
The bullet to use for each item in the generated TOC. If passed as an array (['*', '-', '+']), the bullet point strings will be used based on the header depth.
options.maxdepth
Type: Number
Default: 6
Use headings whose depth is at most maxdepth.
options.firsth1
Type: Boolean
Default: true
Exclude the first h1-level heading in a file. For example, this prevents the first heading in a README from showing up in the TOC.
options.stripHeadingTags
Type: Boolean
Default: true
Strip extraneous HTML tags from heading text before slugifying. This is similar to GitHub markdown behavior.
About

Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Running Tests
Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
$ npm install && npm test

Building docs
(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)
To generate the readme, run the following command:
$ npm install -g verbose/verb#dev verb-generate-readme && verb
Related projects
You might also be interested in these projects:

gfm-code-blocks: Extract gfm (GitHub Flavored Markdown) fenced code blocks from a string. | homepage
markdown-link: Micro util for generating a single markdown link. | homepage
markdown-utils: Tiny helpers for creating consistenly-formatted markdown snippets. | homepage
pretty-remarkable: Plugin for prettifying markdown with Remarkable using custom renderer rules. | homepage
remarkable: Markdown parser, done right. 100% Commonmark support, extensions, syntax plugins, high speed - all in… more | homepage

Contributors



Commits
Contributor



199
jonschlinkert


9
doowb


4
dbooth-boston


3
sapegin


3
Marsup


2
dvcrn


2
maxogden


2
twang2218


2
zeke


1
Vortex375


1
chendaniely


1
Daniel-Mietchen


1
Feder1co5oave


1
garygreen


1
TehShrike


1
citizenmatt


1
mgroenhoff


1
rafaelsteil


1
RichardBradley


1
sethvincent


1
shanehughes3


1
bcho


1
lu22do


Author
Jon Schlinkert

GitHub Profile
Twitter Profile
LinkedIn Profile

License
Copyright  2023, Jon Schlinkert.
Released under the MIT License.

This file was generated by verb-generate-readme, v0.8.0, on July 12, 2023.
\t')

Highlights

Features

Can optionally be used as a remarkable plugin
Returns an object with the rendered TOC (on __INLINE_CODE_3__), as well as a __INLINE_CODE_4__ property with the raw TOC object, so you can generate your own TOC using templates or however you want
Works with repeated headings
Uses sane defaults, so no customization is necessary, but you can if you need to.
filter out headings you don't want
Improve the headings you do want
Use a custom slugify function to change how links are created

Safe!

Won't mangle markdown in code examples in gfm code blocks that other TOC generators mistake as being actual headings (this happens when markdown headings are show in examples, meaning they arent' actually headings that should be in the toc. Also happens with yaml and coffee-script comments, or any comments that use __INLINE_CODE_5__)
Won't mangle front-matter, or mistake front-matter properties for headings like other TOC generators

Usage

__CODE_BLOCK_2__

To allow customization of the output, an object is returned with the following properties:

__INLINE_CODE_6__ {String}: The generated table of contents. Unless you want to customize rendering, this is all you need.
__INLINE_CODE_7__ {Number}: The highest level heading found. This is used to adjust indentation.
__INLINE_CODE_8__ {Array}: Headings tokens that can be used for custom rendering

API

toc.plugin

Use as a remarkable plugin.

__CODE_BLOCK_3__

Usage example

__CODE_BLOCK_4__

Results in:

__CODE_BLOCK_5__

toc.json

Object for creating a custom TOC.

__CODE_BLOCK_6__

toc.insert

Insert a table of contents immediately after an opening __INLINE_CODE_9__ code comment, or replace an existing TOC if both an opening comment and a closing comment (__INLINE_CODE_10__) are found.

(This strategy works well since code comments in markdown are hidden when viewed as HTML, like when viewing a README on GitHub README for example).

Example

__CODE_BLOCK_7__

Would result in something like:

__CODE_BLOCK_8__

Utility functions

As a convenience to folks who wants to create a custom TOC, markdown-toc's internal utility methods are exposed:

__CODE_BLOCK_9__

__INLINE_CODE_11__: render a bullet list from an array of tokens
__INLINE_CODE_12__: linking a heading __INLINE_CODE_13__ string
__INLINE_CODE_14__: slugify a heading __INLINE_CODE_15__ string
__INLINE_CODE_16__: strip words or characters from a heading __INLINE_CODE_17__ string

Example

__CODE_BLOCK_10__

Options

options.append

Append a string to the end of the TOC.

__CODE_BLOCK_11__

options.filter

Type: __INLINE_CODE_18__

Default: __INLINE_CODE_19__

Params:

__INLINE_CODE_20__ {String} the actual heading string
__INLINE_CODE_21__ {Objecct} object of heading tokens
__INLINE_CODE_22__ {Array} all of the headings objects

Example

From time to time, we might get junk like this in our TOC.

__CODE_BLOCK_12__

Unless you like that kind of thing, you might want to filter these bad headings out.

__CODE_BLOCK_13__

options.slugify

Type: __INLINE_CODE_23__

Default: Basic non-word character replacement.

Example

__CODE_BLOCK_14__

options.bullets

Type: __INLINE_CODE_24__

Default: __INLINE_CODE_25__

The bullet to use for each item in the generated TOC. If passed as an array (__INLINE_CODE_26__), the bullet point strings will be used based on the header depth.

options.maxdepth

Type: __INLINE_CODE_27__

Default: __INLINE_CODE_28__

Use headings whose depth is at most maxdepth.

options.firsth1

Type: __INLINE_CODE_29__

Default: __INLINE_CODE_30__

Exclude the first h1-level heading in a file. For example, this prevents the first heading in a README from showing up in the TOC.

options.stripHeadingTags

Type: __INLINE_CODE_31__

Default: __INLINE_CODE_32__

Strip extraneous HTML tags from heading text before slugifying. This is similar to GitHub markdown behavior.

About

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Running Tests

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

__CODE_BLOCK_15__

Building docs

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

__CODE_BLOCK_16__

You might also be interested in these projects:

gfm-code-blocks: Extract gfm (GitHub Flavored Markdown) fenced code blocks from a string. | homepage
markdown-link: Micro util for generating a single markdown link. | homepage
markdown-utils: Tiny helpers for creating consistenly-formatted markdown snippets. | homepage
pretty-remarkable: Plugin for prettifying markdown with Remarkable using custom renderer rules. | homepage
remarkable: Markdown parser, done right. 100% Commonmark support, extensions, syntax plugins, high speed - all in… more | homepage

Contributors

Commits	Contributor
199	jonschlinkert
9	doowb
4	dbooth-boston
3	sapegin
3	Marsup
2	dvcrn
2	maxogden
2	twang2218
2	zeke
1	Vortex375
1	chendaniely
1	Daniel-Mietchen
1	Feder1co5oave
1	garygreen
1	TehShrike
1	citizenmatt
1	mgroenhoff
1	rafaelsteil
1	RichardBradley
1	sethvincent
1	shanehughes3
1	bcho
1	lu22do