Skip to content

Latest commit

 

History

History
196 lines (125 loc) · 4.1 KB

.verb.md

File metadata and controls

196 lines (125 loc) · 4.1 KB

{%= name %} {%= badge("fury") %} {%= badge("travis") %}

{%= description %}

  • Won't mangle markdown in code examples (like headings, coffee or yaml comments in gfm fenced code blocks that other TOC generators mistake as being actual headings)
  • Uses sane defaults, so no customization is necessary, but you can if you need to.
  • Get JSON to generate your own TOC from whatever templates you want to use
  • filter out headings you don't want
  • Improve the headings you do want

Install

{%= include("install-npm", {save: true}) %}

Related projects

{%= related(['remarkable', 'markdown-utils', 'markdown-link', 'gfm-code-blocks', 'pretty-remarkable']) %}

Usage

var toc = require('{%= name %}');

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.json

Object for creating a custom TOC.

toc('# AAA\n## BBB\n### CCC\nfoo').json;

// results in
[ { content: 'AAA', lvl: 1 },
  { content: 'BBB', lvl: 2 },
  { content: '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.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: 3

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.

Running tests

{%= include("tests") %}

Contributing

{%= include("contributing") %}

Author

{%= include("author") %}

License

{%= copyright({start: 2014}) %} {%= license() %}

{%= include("footer") %}