Awesome
verb-toc
Verb plugin that adds middleware for creating and injecting a table of contents into a markdown document.
Table of Contents
(TOC generated by verb using markdown-toc)
Install
Install with npm:
$ npm install --save verb-toc
HEADS UP!!!
This only works with Verb v0.9.0 and higher! (also works with assemble).
Usage
var toc = require('verb-toc');
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 vinylfile
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
About
Related projects
- markdown-toc: Generate a markdown TOC (table of contents) with Remarkable. | homepage
- verb: Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… more | homepage
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Building docs
(This document was generated by verb-generate-readme (a verb generator), please don't edit the readme directly. Any changes to the readme must be made in .verb.md.)
To generate the readme and API documentation with verb:
$ npm install -g verb verb-generate-readme && verb
Running tests
Install dev dependencies:
$ npm install -d && npm test
Author
Jon Schlinkert
License
Copyright © 2017, Jon Schlinkert. Released under the MIT license.
This file was generated by verb-generate-readme, v0.2.1, on January 02, 2017.