Generate a markdown TOC (table of contents) with Remarkable.
npm install markdown-toc> Generate a markdown TOC (table of contents) with Remarkable.
- Install
- CLI
- Highlights
- Usage
- API
* toc.plugin
* toc.json
* toc.insert
* Utility functions
- Options
* options.append
* options.filter
* options.slugify
* options.bullets
* options.maxdepth
* options.firsth1
* options.stripHeadingTags
- About
_(TOC generated by verb using markdown-toc)_
Install with npm:
``sh`
$ npm install --save markdown-toc
`
Usage: markdown-toc [options]
input: The Markdown file to parse for table of contents,
or "-" to read from stdin.
-i: Edit the file directly, injecting the TOC at <!-- 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
`
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
`js
var toc = require('markdown-toc');
toc('# One\n\n# Two').content;
// Results in:
// - One
// - 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
Use as a remarkable plugin.
`js
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
`js`
var results = render('# AAA\n# BBB\n# CCC\nfoo\nbar\nbaz');
Results in:
Object for creating a custom TOC.
`js
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 } ]
`
Insert a table of contents immediately after an _opening_ code comment, or replace an existing TOC if both an _opening_ comment and a _closing_ comment () 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
`
- old toc 1
- old toc 2
- old toc 3
Would result in something like:
- abc
- xyz
abc
This is a b c.xyz
This is x y z.
$3
As a convenience to folks who wants to create a custom TOC, markdown-toc's internal utility methods are exposed:
js
var toc = require('markdown-toc');
`*
: 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 stringExample
`js
var result = toc('# AAA\n## BBB\n### CCC\nfoo');
var str = '';result.json.forEach(function(heading) {
str += toc.linkify(heading.content);
});
`Options
$3
Append a string to the end of the TOC.
js
toc(str, {append: '\n_(TOC generated by Verb)_'});
`$3
Type:
Default:
Params:
*
{String} the actual heading string
* ele {Objecct} object of heading tokens
* arr {Array} all of the headings objectsExample
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.
js
function removeJunk(str, ele, arr) {
return str.indexOf('...') === -1;
}var result = toc(str, {filter: removeJunk});
//=> beautiful TOC
`$3
Type:
Default: Basic non-word character replacement.
Example
js
var str = toc('# Some Article', {slugify: require('uslug')});
`$3
Type:
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.$3
Type:
NumberDefault:
Use headings whose depth is at most maxdepth.
$3
Type:
Default:
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.
$3
Type:
Default:
Strip extraneous HTML tags from heading text before slugifying. This is similar to GitHub markdown behavior.
About
$3
* gfm-code-blocks: Extract gfm (GitHub Flavored Markdown) fenced code blocks from a string. | homepage fenced code blocks from a string.")
* markdown-link: Micro util for generating a single markdown link. | homepage
* markdown-utils: Micro-utils for creating 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
$3
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
$3
| Commits | Contributor |
| --- | --- |
| 196 | jonschlinkert |
| 4 | stefanwalther |
| 3 | Marsup |
| 2 | dvcrn |
| 2 | maxogden |
| 2 | twang2218 |
| 2 | angrykoala |
| 2 | zeke |
| 1 | Vortex375 |
| 1 | owzim |
| 1 | chendaniely |
| 1 | Daniel-Mietchen |
| 1 | Feder1co5oave |
| 1 | garygreen |
| 1 | TehShrike |
| 1 | citizenmatt |
| 1 | rafaelsteil |
| 1 | RichardBradley |
| 1 | sethvincent |
| 1 | lu22do |
$3
_(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:
sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
`$3
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:
sh
$ npm install && npm test
``Jon Schlinkert
* github/jonschlinkert
* twitter/jonschlinkert
Copyright © 2017, Jon Schlinkert.
Released under the MIT License.
*
_This file was generated by verb-generate-readme, v0.6.0, on September 19, 2017._