oh, we don't use comments here, do we?

[git.ikiwiki.info.git] / 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 60edaffcb7fc62dce2c464d38a865f4eeddffa17..482dad70b6c1e9688b01946f3dd5d68a79ea28c3 100644 (file)
--- a/doc/todo/toc-with-human-readable-anchors.mdwn
+++ b/doc/todo/toc-with-human-readable-anchors.mdwn
@@ -24,6 +24,8 @@ 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
 
 [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:
 
 The second step is to generate those headings. There are two ways of
 doing this:
 


@@ -31,6 +33,26 @@ doing this:
     add `id` anchors when using [Text::Multimarkdown][] which is
     simply a matter of adding `multimarkdown: 1` in the setup file
 
     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.
 
  2. enable the [[plugins/headinganchors]] plugin. if multimarkdown is
     disabled, this can also provide usable identifiers.