Docpad plugin to generate table of contents of a document.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Table of Contents Plugin for DocPad

A DocPad plugin to generate tables of content from document header data


I'm very new to DocPad, CoffeeScript, and Node in general, so please consider this plugin very beta.

Your questions, feedback, and (pull) requests are greatly appreciated.


npm install --save docpad-plugin-tableofcontents



Default: ["html"]

Sets document types to parse. Only html is supported currently.


Default: true

If true, only documents with the specified metadata parameter set as true will generate table of contents data.


Default: 'toc'

If requireMetadata is set, this is the field that must be set true in the document metadata.


Default: true

So that the table of contents may be generated with links to page sections, header ids should set. The plugin can automatically generate these ids, if one is not already present. It will not overwrite any id present.


Default: ``

Value will be added as a prefix to the automatically generated header ids.


Default: 'h2,h3,h4,h5,h6'

A list of header selectors to search. By default, it is assumed H1 will contain the page title, and won't need to be included in the table of contents.

This value is passed directly to the Document.querySelectorAll DOM function, and should contain appropriately valid selectors.


Default: 2

Integer containing header level we begin with.

Depreciated, will be eventually determined from headerSelectors.


The plugin searches the document for the specified headers, returning an array of TableofcontentItem objects. This object has the following properties:

  • text Header text.
  • id id of header, use to create links to page sections.
  • children array of TableofcontentItem objects, with the next level of headers.

Similar to docpad-plugin-menu, using a partial as a template for output is the best method.

Create a partial:

<% renderToc = (items) => %>
<ol class="toc">
    <% for item in items: %>
        <li><a href="#<%= %>"><%= item.text %></a>
            <% if item.children: %>
                <%- renderToc(item.children) %>
            <% end %>
    <% end %>
<% end %>
<%= renderToc @tocItems %>

Include the partial in your template.

<div class="sidebar">
    <%- @partial('', {tocItems: @document.tableOfContents}) %>

Limitations, Known Bugs

  • This plugin only works with html. I would like to eventually add parsing of additional document types.
  • Need to enforce uniqueness in header ids.
  • Selected elements are not filtered / validated / checked.
  • Determine rootHeaderLevel from headerSelectors.
  • Testing.
  • Better error handing and debug logs.


Please review the file.


My work is built on the efforts of others, I hope mine will contribute to yours. Enjoy!