## Usage

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

### Two Steps

**1. [Register the middleware](#usage-with-template)**

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:

```html
<!!-- toc -->
```

### Templates.js

Usage with [template.js][templates]:

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

```js
templates.preRender(/\.md$/, toc(template));
```

This project's [verbfile](./.verb.md) 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. 

```js
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.

```js
templates.render('README.md', function(err, content) {
  console.log(content);
});
```
Visit [templates][] for documentation.


### Verb

Usage with [verb][]:

```js
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][]:

```js
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.

```html
<!!-- toc -->
```