doc/todo/toc-with-human-readable-anchors.mdwn

   1 The [[/plugins/toc]] plugin is very useful but it creates anchors with names such as #index1h3
   2
   3 In #ikiwiki today, another user and I were in agreement that an option for human readable anchors would be preferable.
   4
   5 > +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]]
   6
   7 ----
   8
   9 I started looking into this again after getting annoyed at the
  10 unreadable anchors, and here's what I came up with.
  11
  12 [[!template  id=gitbranch branch=anarcat/toc-recycle-id author="[[anarcat]]"]]
  13
  14 The first step is to fix [[plugins/toc]] to use headings: we can
  15 figure out how to generate those later, but it would be nice if the
  16 toc directive would just reuse existing headings instead of relying on
  17 its own. I do this by simply checking if there's a `id` field (which
  18 is, by standard, unique) and reuse that when building the table of
  19 contents. This requires parsing HTML element attributes, but that
  20 shouldn't impact performance too much, hopefully. The old IDs are
  21 still generated for backwards compatibility. This is done in
  22 my [toc-recycle-id branch][] (see [921a264][]).
  23
  24 [921a264]: https://gitlab.com/anarcat/ikiwiki/commit/27d5d9d126b6b675ad273ebd63095df0c921a264
  25 [toc-recycle-id branch]: https://gitlab.com/anarcat/ikiwiki/commits/toc-id-recycle
  26
  27 The second step is to generate those headings. There are two ways of
  28 doing this:
  29
  30  1. enable multimarkdown. by default, the [[plugins/mdwn]] plugin will
  31     add `id` anchors when using [Text::Multimarkdown][] which is
  32     simply a matter of adding `multimarkdown: 1` in the setup file
  33
  34  2. enable the [[plugins/headinganchors]] plugin. if multimarkdown is
  35     disabled, this can also provide usable identifiers.
  36
  37 An issue I had with the latter plugin was that it did not work if
  38 multimarkdown was enabled, as it doesn't match headings if they
  39 already have a `id` attribute. It also doesn't deal very well with
  40 non-ASCII characters: they get basically garbled into their numeric
  41 representation. I have therefore written a derivative of the
  42 headinganchor plugin called [[plugins/contrib/i18nheadinganchors]] to
  43 work around those issues.
  44
  45 It would be great to see the `toc` part of this patchset merged, at
  46 least. It could also be a configurable option, but that seems overkill
  47 considering that backwards compatibility is kept... --[[anarcat]]
  48
  49 [Text::Multimarkdown]: http://search.cpan.org/search?mode=dist&query=Text%3A%3AMarkdown
  50
  51 [[!tag wishlist patch]]