anatoo / metalsmith-autotoc

[UNMAINTAINED] A metalsmith plugin for generating table of contents.

---

📌 Deprecation Notice

This repository is deprecated and no more work will be done on this. Please use metalsmith/table-of-contents.

---

metalsmith-autotoc

A metalsmith plugin to generate table of contents of a document.

This plugin generate table of contents object to document's metadata.

Installation

$ npm install metalsmith-autotoc

Configuration

headerIdPrefix

Default: ``

This value will be added to generated header ids as a prefix.

selector

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

A list of header selectors to search.

Example

Source file src/index.html:

---
autotoc: true
template: 'layout.eco'
---
<h2>aaa</h2>
<p>paragraph</p>

<h3>bbb</h3>
<p>paragraph</p>

<h3>ccc</h3>
<p>paragraph</p>

<h2>ddd</h2>
<p>paragraph</p>

Template file templates/layout.eco:

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

<% if @toc: %>
<%- renderToc(@toc) %>
<% end %>

<%- @contents %>

Build file build.js:

var metalsmith = require('metalsmith');
var autotoc = require('metalsmith-autotoc');
var templates = require('metalsmith-templates');

metalsmith(__dirname)
  .source('./src')
  .destination('./dest')
  .use(autotoc({selector: 'h2, h3, h4'}))
  .use(templates({
    engine: 'eco',
    directory: './templates'
  }))
  .build();

Results file dest/index.html:

<ol class="toc">
  <li><a href="#aaa">aaa</a>
    <ol class="toc">
      <li><a href="#bbb">bbb</a></li>
      <li><a href="#ccc">ccc</a></li>
    </ol>
  </li>
  <li><a href="#ddd">ddd</a></li>
</ol>

<h2 id="aaa">aaa</h2>
<p>paragraph</p>

<h3 id="bbb">bbb</h3>
<p>paragraph</p>

<h3 id="ccc">ccc</h3>
<p>paragraph</p>

<h2 id="ddd">ddd</h2>
<p>paragraph</p>

License

MIT

metalsmith-autotoc's Issues

Documentation for other template languages

The example in the README is for .eco templates, but I can't see how exactly it'd work with Handlebars or AN Other templating language - can you update the docs with a little example?

Duplicate IDs

I'm having an issue on my site where duplicate IDs are created when there are two headings with the same inner text.

<h2 id="first">First</h2>
<h3 id="overview">Overview</h3>
<h2 id="second">Second</h2>
<h3 id="overview">Overview</h3>

Would you consider adding something to make these unique? Perhaps like appending an index number.

<h2 id="first">First</h2>
<h3 id="overview">Overview</h3>
<h2 id="second">Second</h2>
<h3 id="overview2">Overview</h3>

Thanks!

Install issues related to Node 4.x

Seems the "Contextify" dependency has issues with recent Node versions, as noted here:

brianmcd/contextify#180

I'm not sure how to fix this, only discovering it when I tried to install this plugin today. Might there be a workaround for this module so that it could be installed?

possibility to use another templating engine?

It appears that this plugin seems to be linked to eco rendering engine.

Could it be possible to use another templating engine such as handlebars?

This could be the opportunity to switch from metalsmith-template to metalsmith-layout.