In #ikiwiki today, another user and I were in agreement that an option for human readable anchors would be preferable.
-[[!tag wishlist]]
+> +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.
+
+[[!template id=gitbranch branch=anarcat/toc-recycle-id author="[[anarcat]]"]]
+
+The first step is to fix [[plugins/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][]).
+
+[921a264]: https://gitlab.com/anarcat/ikiwiki/commit/27d5d9d126b6b675ad273ebd63095df0c921a264
+[toc-recycle-id branch]: https://gitlab.com/anarcat/ikiwiki/commits/toc-id-recycle
+
+> [[Merged|done]] --[[smcv]]
+
+The second step is to generate those headings. There are two ways of
+doing this:
+
+ 1. enable multimarkdown. by default, the [[plugins/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 [[!cpan 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 [[plugins/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 [[plugins/contrib/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]]
+
+[Text::Multimarkdown]: http://search.cpan.org/search?mode=dist&query=Text%3A%3AMarkdown
+
+[[!tag wishlist patch]]