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.

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

Merged --smcv

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

   Sure - but then does discount introduce those identifiers in headings?

   Only if you ask for a table of contents, which ikiwiki doesn't. If you want it to have a flag to produce the IDs even without enabling its built-in ToC support, that would be a feature request for discount, not ikiwiki. Until/unless it does, there's always headinganchors. --s

   And what about the patch to recycle those identifiers? --anarcat

   I already merged it, and added a regression test. Sorry, I forgot to close this todo at the time. --s

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