Template-toc NPM

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

1. Register the middleware

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