]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/blob - doc/todo/toc-with-human-readable-anchors.mdwn
resolved
[git.ikiwiki.info.git] / 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
3 In #ikiwiki today, another user and I were in agreement that an option for human readable anchors would be preferable.
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]]
7 ----
9 I started looking into this again after getting annoyed at the
10 unreadable anchors, and here's what I came up with.
12 [[!template  id=gitbranch branch=anarcat/toc-recycle-id author="[[anarcat]]"]]
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][]).
24 [921a264]: https://gitlab.com/anarcat/ikiwiki/commit/27d5d9d126b6b675ad273ebd63095df0c921a264
25 [toc-recycle-id branch]: https://gitlab.com/anarcat/ikiwiki/commits/toc-id-recycle
27 > [[Merged|done]] --[[smcv]]
29 The second step is to generate those headings. There are two ways of
30 doing this:
32  1. enable multimarkdown. by default, the [[plugins/mdwn]] plugin will
33     add `id` anchors when using [Text::Multimarkdown][] which is
34     simply a matter of adding `multimarkdown: 1` in the setup file
36     > I don't think multimarkdown is a good solution. It served a useful
37     > purpose when we were defaulting to [[!cpan Text::Markdown]] or to
38     > `markdown.pl`, but now that we're using Discount by default,
39     > Multimarkdown is mostly a trap for the unwary - it's a less predictable
40     > and (in general) less featureful parser than Discount. Ideally we'd
41     > always be using CommonMark or Discount these days, but as
42     > far as I know there's still no API-stable CommonMark library. --[[smcv]]
44     > > Sure - but then does discount introduce those identifiers in headings?
45     > >
46     > > > Only if you ask for a table of contents, which ikiwiki doesn't.
47     > > > If you want it to have a flag to produce the IDs even without enabling
48     > > > its built-in ToC support, that would be a feature request for discount,
49     > > > not ikiwiki. Until/unless it does, there's always headinganchors. --s
50     > >
51     > > And what about the patch to recycle those identifiers? --[[anarcat]]
52     > > >
53     > > > I already merged it, and added a regression test. Sorry, I forgot
54     > > > to close this todo at the time. --s
56  2. enable the [[plugins/headinganchors]] plugin. if multimarkdown is
57     disabled, this can also provide usable identifiers.
59 An issue I had with the latter plugin was that it did not work if
60 multimarkdown was enabled, as it doesn't match headings if they
61 already have a `id` attribute. It also doesn't deal very well with
62 non-ASCII characters: they get basically garbled into their numeric
63 representation. I have therefore written a derivative of the
64 headinganchor plugin called [[plugins/contrib/i18nheadinganchors]] to
65 work around those issues.
67 It would be great to see the `toc` part of this patchset merged, at
68 least. It could also be a configurable option, but that seems overkill
69 considering that backwards compatibility is kept... --[[anarcat]]
71 [Text::Multimarkdown]: http://search.cpan.org/search?mode=dist&query=Text%3A%3AMarkdown
73 [[!tag wishlist patch]]