.verb.md

HEADS UP!!!

This only works with Verb v0.9.0 and higher! (also works with [assemble][]).

Usage

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

Basic example

In your verbfile.js:

module.exports = function(verb) {
  verb.extendWith(require('verb-toc'));
  // do stuff, render templates, write files
};

Add a <!-- toc --> HTML comment to any markdown document where you want a table of contents to be injected. For the TOC middleware to run, you'll need to either call the postLayout and preWrite middleware handlers yourself, or follow the example below.

---

Docs

Middleware

The main export is a function that when invoked with an instance of verb will automatically register two middleware functions:

• a .postLayout (createToc) middleware that creates the table of contents after a layout has been applied
• a .preWrite (injectToc) middleware that injects the table of contents back into the document after all other plugins have run.

Both middleware functions are also exposed as properties on module.exports, so you can try other stages if you want. Be warned that there are pros and cons to most middleware stages, in my own experience these stages work really well and seem to result in the fewest unwanted side-effects.

toc event

If you want to completely customize how the TOC is injected, you can listen for the toc event.

Params

• file Exposes the vinyl file being rendered

Example

verb.on('toc', function(file, next) {
  // do stuff to `file.contents`, then call next
  next();
});

Register the middleware

In your verbfile.js:

module.exports = function(verb) {
  verb.extendWith(require('verb-toc'));
  
  // use any template engine, but you must call `.renderFile` 
  // (below) to trigger the necessary middleware stages
  verb.engine('*', require('engine-base'));

  // example task
  verb.task('docs', function(cb) {
    return verb.src('docs/*.md', { cwd: __dirname })
      .pipe(app.renderFile('*'))
      .pipe(verb.dest('dist'));
  });

  verb.task('default', ['docs']);
};

(In v0.9.0 and higher, verbfiles that export a function are recognized by verb as "generators", allowing them to be locally or globally installed, and composed with other generators. You can alternatively export an instance of verb, but it's not as fun...)

verb config

Enable or disable Table of Contents rendering, or pass options on the verb config object in package.json.

Example

{
  "name": "my-project",
  "verb": {
    "toc": true
  }
}

verb CLI

toc

Disable or enable TOC rendering from the command line.

Enable

Enable the table of contents for the current build:

$ verb --toc

Disable

Disable the table of contents for the current build:

$ verb --toc=false

Save to project's verb config

Persist TOC settings for a project to the verb config object in package.json:

Enable

Enable the table of contents for a project:

$ verb --config=toc

Disable

Disable the table of contents for a project:

$ verb --config=toc:false

Save to global verb config

Persist TOC settings to be used as global:

Enable

Enable the table of contents for a project:

$ verb --global=toc
# or
$ verb -g=toc

Disable

Disable the table of contents for a project:

$ verb --global=toc:false
# or
$ verb -g=toc:false