doc/todo/allow_toc_to_skip_entries.mdwn

   1 [[!template  id=gitbranch branch=anarcat/toc-skip author="[[anarcat]]"]]
   2
   3 a long-standing irritationf the [[plugins/toc]] plugin is that it counts *all* headings in the document. since it's frequently the case that themes will use the first H1 to show a title (and that there's no way to "bump" the level of headings generated by the markup), you often end up with a table of contents that looks like this:
   4
   5  * TITLE
   6  * Heading 1
   7    * Subheading 1
   8  * Heading 2
   9
  10 ... even though the content is actually something like:
  11
  12     # Heading 1
  13     ## Subheading 2
  14     # Heading 2
  15
  16 That's a bit confusing. I would expect the table of contents to only have:
  17
  18  * Heading 1
  19    * Subheading 1
  20  * Heading 2
  21
  22 ... and somehow ignore my title.
  23
  24 That is hard to fix without changing the theme significantly. ikiwiki themes frequently workaround that problem by showing the title using another markup element, generally a `<span>`. But I find that confusing as well, because `<span>` is a generic, non-semantic element, which, even worse, is by default not a "block" like a heading. In bootstrap, for example, you would need to copy all the logic surrounding headings to a theme customization to make it work, but that leads to a lot of CSS duplication.
  25
  26 There should really be a way to skip those entries. The patch mentioned here does this by doing a tiny modification to `toc.pm` to skip headings with the magic `nocount` class. The naming comes from [Phil Archer's Automatic Heading Numbering CSS hack](https://philarcher.org/diary/2013/headingnumbers) and could be changed, but it seemed logical to me. The result can be seen in action in: <https://anarc.at/blog/2019-11-20-file-monitoring-tools/>.
  27
  28 Thank you for your consideration.
  29
  30 [[!tag patch]]