Feature #9535: Make link to anchor available when hover'ing a title
Have ikiwiki generate anchor names based on heading's text
Currently, the toc plugin gives us anchor names numbered in function of the page title's hierarchy. This causes at least two problems:
- These names (and the corresponding links) then change when adding or re-ordering sections, and then we can't (or rather, should not) be using them to point people to a specific section, at least on communication media that's archived.
- It prevents us from automatically displaying links to these anchors when hover'ing a title (see parent ticket).
IIRC there's a third-party plugin that forks the toc one and generates anchor names based on the title's text.
#1 Updated by intrigeri over 4 years ago
- Subject changed from Have ikiwiki generate anchor names based on title's text to Have ikiwiki generate anchor names based on heading's text
- Status changed from Confirmed to In Progress
- % Done changed from 0 to 10
I had a quick first look, and indeed, the headinganchors plugin (included in ikiwiki) trivially adds
id="#nice_anchor" to headings, which is a good start: even without any other change, it would avoid the need, in most cases, to manually add anchors, when we need to refer people to a particular section of a page.
However, that plugin does not insert links inside the headings, so that's not enough to satisfy the parent ticket's requirements. It seems to me (and it was suggested on https://ikiwiki.info/plugins/headinganchors/discussion/), that the headinganchors plugin's functionality should be re-used by the toc plugin, to avoid generating two separate sets of anchors (and in turn, to avoid having problematic
#indexNhM links being displayed and then published). See also https://ikiwiki.info/todo/toc-with-human-readable-anchors/.
#2 Updated by sajolida over 4 years ago
Yes, I had a look at this plugin a while ago and discarded using it. Probably because:
- It is not integrated with toc as you pointed out.
- It creates ugly anchors. https://tails.boum.org/support/faq#debian would become https://tails.boum.org/support/faq#why_is_tails_based_on_debian_and_not_on_another_distribution.
- Anchors should be more stable than currently but could still get broken by a change in the title.
So for some time I preferred creating anchors manually for some years. Now I agree that it is not a perfect solution either and would love to have something less manual. Ideally, anchors would be created automatically but we could overwrite them manually if we want something shorter or if we modify the title. But maybe these two issues are not blockers.
#3 Updated by intrigeri over 4 years ago
So for some time I preferred creating anchors manually for some years. Now I agree that it is not a perfect solution either and would love to have something less manual.
Thanks for the feedback. I share the concerns you have.
Ideally, anchors would be created automatically but we could overwrite them manually if we want something shorter or if we modify the title.
I can't think of a way to implement the "override them manually" given how Markdown and ikiwiki work, so I've tried to think of it a bit harder. I see two cases:
- places where we never bothered manually creating anchors, and then the only available ones are generated by the
tocplugin: for those, I bet that in most cases, anchor names based on the title will be more stable than the ones we currently have;
- places where we have already manually created anchors (generally because we link to them from some other part of the website): for those, as long as the manually added anchor still works, I think it's OK if it doesn't override the automatically generated one; I mean, we could simply leave the current manual anchors in place, so:
- existing links will still work, and we can still use these nice carefully and manually crafted organic anchors on the website;
- but the
headinganchorsplugin will create additional anchors automatically; those will be less nice, but more visible (once links on hover are added) and thus more often shared, while a bit less stable than the manually crafted ones; this is certainly not perfect, but in my experience, currently the links that are most often shared by humans on support channels (except by f****sts like you and I, perhaps) are those generated by the
tocplugin, which are even worst, so IMO this would be an improvement over the current state of things.
=> I'm now quite convinced that the ability to override automatically-generated anchors is not a blocker, as long as manually added ones still can be linked to.
However, IMO the integration with the
toc plugin is a blocker: having three orthogonal sets of anchors (worst case) sounds totally insane to me.
#4 Updated by sajolida over 4 years ago
Yes, I'm fine with having the manually created anchors on top of the automatically generated ones when we need them. Another option could be to write the resulting HTML code for the titles and the magic anchor link ourselves instead of markdown. I also suspect that we might not need to override the automatically generated titles that often and we'll figure out something when we need it... The FAQ is quite an extreme example.
So I agree that this first issue is not a blocker but that the integration with the `toc` plugin is a blocker.
Next step is to find someone to write perl, right?
#7 Updated by intrigeri almost 3 years ago
- QA Check deleted (
I'd like to keep this around, with Low priority. Who knows, now that I have more free time, perhaps I'll want to code it some day, and having a list of such things "to do some day maybe" is useful when procrastinating in a structure way :) Same for the parent ticket.
#8 Updated by intrigeri over 2 years ago
Possibly useful progress on this front: http://anarc.at/blog/2017-04-29-free-software-activities-april-2017/