The toc plugin is very useful but it creates anchors with names such as #index1h3

In #ikiwiki today, another user and I were in agreement that an option for human readable anchors would be preferable.

+1 - i would love to see that happen too. Here's a patch I wrote a while back for similar functionality in moinmoin: https://svn.koumbit.net/koumbit/trunk/patches/moinmoin/nice_headings.patch -- anarcat


I started looking into this again after getting annoyed at the unreadable anchors, and here's what I came up with.

Available in a git repository branch.
Branch: anarcat/toc-recycle-id
Author: anarcat

The first step is to fix toc to use headings: we can figure out how to generate those later, but it would be nice if the toc directive would just reuse existing headings instead of relying on its own. I do this by simply checking if there's a id field (which is, by standard, unique) and reuse that when building the table of contents. This requires parsing HTML element attributes, but that shouldn't impact performance too much, hopefully. The old IDs are still generated for backwards compatibility. This is done in my toc-recycle-id branch (see 921a264).

The second step is to generate those headings. There are two ways of doing this:

  1. enable multimarkdown. by default, the mdwn plugin will add id anchors when using Text::Multimarkdown which is simply a matter of adding multimarkdown: 1 in the setup file

    I don't think multimarkdown is a good solution. It served a useful purpose when we were defaulting to Text::Markdown or to markdown.pl, but now that we're using Discount by default, Multimarkdown is mostly a trap for the unwary - it's a less predictable and (in general) less featureful parser than Discount. Ideally we'd always be using CommonMark or Discount these days, but as far as I know there's still no API-stable CommonMark library. --smcv

  2. enable the headinganchors plugin. if multimarkdown is disabled, this can also provide usable identifiers.

An issue I had with the latter plugin was that it did not work if multimarkdown was enabled, as it doesn't match headings if they already have a id attribute. It also doesn't deal very well with non-ASCII characters: they get basically garbled into their numeric representation. I have therefore written a derivative of the headinganchor plugin called i18nheadinganchors to work around those issues.

It would be great to see the toc part of this patchset merged, at least. It could also be a configurable option, but that seems overkill considering that backwards compatibility is kept... --anarcat