Feature #9536

Have ikiwiki generate anchor names based on heading's text

Added by intrigeri 2015-06-05 11:23:53 . Updated 2019-03-08 15:45:17 .

Status:
Confirmed
Priority:
Low
Assignee:
Category:
Infrastructure
Target version:
Start date:
2015-06-05
Due date:
% Done:

10%

Feature Branch:
Type of work:
Code
Blueprint:

Starter:
Affected tool:
Deliverable for:

Description

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.

Subtasks

History

#1 Updated by intrigeri 2015-06-05 11:37:24

  • 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 2015-06-06 10:45:51

Yes, I had a look at this plugin a while ago and discarded using it. Probably because:

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 2015-06-09 19:02:26

> 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 toc plugin: 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 headinganchors plugin 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 toc plugin, 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 2015-06-10 11:18:09

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?

#5 Updated by intrigeri 2015-06-10 12:55:54

> Next step is to find someone to write perl, right?

I think that proposing a design and reaching an agreement upstream would be a first good step. But indeed, without anyone ready to implement our proposal, it would perhaps be a bit pointless.

#6 Updated by sajolida 2016-11-04 13:54:48

  • Priority changed from Normal to Low
  • QA Check set to Info Needed

Shall we drop this?

#7 Updated by intrigeri 2016-11-05 13:50:17

  • QA Check deleted (Info Needed)

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 2017-04-30 15:05:58

Possibly useful progress on this front: http://anarc.at/blog/2017-04-29-free-software-activities-april-2017/

#10 Updated by intrigeri 2019-03-07 15:34:19

  • Assignee deleted (intrigeri)

It’s unlikely I’ll have time to work on this any time soon. Even when bored on a rainy Sunday, I always find something else to do that’s both more fun and more useful for our users.

#11 Updated by intrigeri 2019-03-08 15:45:17

  • Status changed from In Progress to Confirmed
  • Type of work changed from Research to Code