X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/d33b31f70638025f19fdfa03a8c2e609faca792a..e0ce38dc42f461539a7c8f0594b95473d4494689:/doc/todo/toc-with-human-readable-anchors.mdwn

diff --git a/doc/todo/toc-with-human-readable-anchors.mdwn b/doc/todo/toc-with-human-readable-anchors.mdwn
index 0f358f4e6..482dad70b 100644
--- a/doc/todo/toc-with-human-readable-anchors.mdwn
+++ b/doc/todo/toc-with-human-readable-anchors.mdwn
@@ -4,4 +4,70 @@ In #ikiwiki today, another user and I were in agreement that an option for human
 
 > +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]]
 
-[[!tag wishlist]]
+----
+
+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]]