diff options
author | anarcat <anarcat@web> | 2020-03-15 16:50:55 -0400 |
---|---|---|
committer | admin <admin@branchable.com> | 2020-03-15 16:50:55 -0400 |
commit | 1d7d7cbcb7b835655478bdccb52368439f6381b8 (patch) | |
tree | 4a944fb5a032389eed520e75fd141e381d9ca453 /doc | |
parent | d3062f5c77db32d361ba367757f7425cf2364243 (diff) | |
download | ikiwiki-1d7d7cbcb7b835655478bdccb52368439f6381b8.tar ikiwiki-1d7d7cbcb7b835655478bdccb52368439f6381b8.tar.gz |
add way to skip toc entries
Diffstat (limited to 'doc')
-rw-r--r-- | doc/todo/allow_toc_to_skip_entries.mdwn | 28 |
1 files changed, 28 insertions, 0 deletions
diff --git a/doc/todo/allow_toc_to_skip_entries.mdwn b/doc/todo/allow_toc_to_skip_entries.mdwn new file mode 100644 index 000000000..45137d7a2 --- /dev/null +++ b/doc/todo/allow_toc_to_skip_entries.mdwn @@ -0,0 +1,28 @@ +[[!template id=gitbranch branch=anarcat/toc-skip author="[[anarcat]]"]] + +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: + + * TITLE + * Heading 1 + * Subheading 1 + * Heading 2 + +... even though the content is actually something like: + + # Heading 1 + ## Subheading 2 + # Heading 2 + +That's a bit confusing. I would expect the table of contents to only have: + + * Heading 1 + * Subheading 1 + * Heading 2 + +... and somehow ignore my title. + +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. + +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/>. + +Thank you for your consideration. |