Table of Contents Plugin for DocPad

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

Note:

I'm very new to DocPad, CoffeeScript, and Node in general, so please consider this plugin very beta. It's not quite ready for npm yet. Needs a couple more days of testing.

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

Installation

Run npm install --save docpad-plugin-tableofcontents command in your DocPad project root.

Configuration

documentExtensions

Default: ["html"]

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

requireMetadata

Default: false

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

requiredMetadataField

Default: 'toc'

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

addHeaderIds

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.

headerSelectors

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.

rootHeaderLevel

Default: 2

Integer containing header level we begin with.

Depreciated, will be eventually determined from headerSelectors.

Usage

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.

1. Create a toc.html.eco partial:

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

2. Include the partial in your template.

<div class="sidebar">
    <h3>Contents</h3>
    <%- @partial('toc.html.eco', {tocItems: @document.tableOfContents}) %>
</div>

Limitations, Known Bugs

• This plugin only works with html. I would like to eventually add parsing of additional document types.
• This plugin runs each time an html document is rendered. This may happen several times, as partials and layouts are applied, and depending on your headerSelectors, the table of contents may be updated. I use tableOfContents in a partial, so updates on later renders do not affect me. This may be an issue or feature depending on how you use the plugin. I'd love some feedback or help with this.
• 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.

History

Please review the History.md file.

License

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