template-toc

Middleware for generating a markdown-formatted table of contents with Template, or Template-based applications

• Install
• Usage
  • Two Steps
  • Templates.js
  • Verb
  • Assemble
• Pro-tip
• Related projects
• Running tests
• Contributing
• Author
• License

(TOC generated by verb)

Install

Install with npm

$ npm i template-toc --save

Usage

var toc = require('template-toc');

Two Steps

1. Register the middleware

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

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2015 Jon Schlinkert Released under the MIT license.

---

This file was generated by verb on December 15, 2015.