template-toc
v0.6.2
Published
Middleware for generating a markdown-formatted table of contents with Template, or Template-based applications
Downloads
524
Maintainers
Readme
template-toc
Middleware for generating a markdown-formatted table of contents with Template, or Template-based applications
(TOC generated by verb)
Install
Install with npm
$ npm i template-toc --save
Usage
var toc = require('template-toc');
Two Steps
Register with templates, verb, assemble or any other application based on templates
2. Add a TOC marker
Add the following to any markdown file that should get a Table of Contents:
<!-- toc -->
Templates.js
Usage with template.js:
var Templates = require('templates');
var templates = new Templates();
Pre-render middleware
If you want the TOC to be generated before layouts are used or partials are injected into pages, use the .preRender()
method.
templates.preRender(/\.md$/, toc(template));
This project's verbfile is a good example. Verb uses this middleware with .preRender()
so that the generated TOC only includes "top-level" headings that are in the template, and none of the headings from partials are includes.
Post-render middleware
If you want the TOC to be generated after layouts are used or partials are injected into pages, use the .postRender()
method.
templates.postRender(/\.md$/, toc(template));
Rendering templates
Once the middlware is setup, any templates with a .md
extension and a <!-- toc -->
comment will have a TOC injected.
templates.render('README.md', function(err, content) {
console.log(content);
});
Visit templates for documentation.
Verb
Usage with verb:
var verb = require('verb'); // or assemble
var app = verb();
app.preRender(/\.md$/, toc(app));
// or
app.postRender(/\.md$/, toc(app));
Visit verb for documentation.
Assemble
Usage with assemble:
var assemble = require('assemble');
var app = assemble();
app.preRender(/\.md$/, toc(app));
// or
app.postRender(/\.md$/, toc(app));
Visit assemble for documentation.
Pro-tip
Escaping
If, for some reason, you need to use the <!- toc -->
comment in documentation and you do not want it to be rendered, just add an extra !
after the first angle bracket, and the extra !
will be removed but the TOC will not be rendered.
<!-- toc -->
Related projects
- markdown-toc: Generate a markdown TOC (table of contents) with Remarkable. | homepage
- markdown-utils: Micro-utils for creating markdown snippets. | homepage
- remarkable: Markdown parser, done right. 100% Commonmark support, extensions, syntax plugins, high speed - all in… more | homepage
- templates: System for creating and managing template collections, and rendering templates with any node.js template engine.… more | homepage
- verb: Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… more | homepage
Running tests
Install dev dependencies:
$ npm i -d && npm test
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Author
Jon Schlinkert
License
Copyright © 2015 Jon Schlinkert Released under the MIT license.
This file was generated by verb on December 15, 2015.