Section Numbers

[zafarali]

Is there a way to have section numbers or relative links to parts of a paper?

For example, I wanted to link to the "Attentional Interfaces" bit of the Augmented RNNs paper but I couldn't find an easy way to do this.

Perhaps we should add a little hyperlink chain that appears next to section headings on hover allowing one to copy paste links to sections in a paper.

[shancarter]

Yes, we should totally do this.

[bfirsh]

@shancarter Do you have any thoughts on how this should be implemented? Automated or hard-coded numbering?

Hard-coding them is certainly the simplest implementation, and probably means the URLs will be more robust.

[shancarter]

Yeah, we're in the middle of a little bit of a rewrite, so the actual implementation will depend on that landing first. As for other details, the solutions I see are:

1. Force authors to give ids for all headings (h2-h6) so we can link to any of them.

2. Automatically assign ids for all headings based on the text content of the heading, like some versions of markdown do.

3. Automatically assign ids for all headings based on numeric sections (for example, id="section-1.4.1")

All have strengths and weaknesses. (1) is the most robust but most annoying for authors, (2, 3) are brittle but convenient.

@colah or @ludwigschubert have any preferences?

[ludwigschubert]

I'm a big fan of 1, as I believe robust URLs are very important in publications. We could encourage via console.debugs during authoring and enforce at editing time.

Yet I'm also a big fan of 2/3, as handwritten IDs could get out of sync and are additional effort.

Overall: weak preference for 2/3, with even weaker preference for 3 or a combination of numeric and textContent.

[shancarter]

Thinking a little more, maybe we should split up this behavior up a little.

• If the dt-article component in distill template sees an id on any h2-h6 element, it should add a little # link to the anchor for that section, or make the whole heading. If there is no id it will not do anything. This seem uncontroversial.

The question then becomes what to do with headers that don't have an explicit id. I think it would be annoying to authors to have to manually add an id to every header. The two options seem to be:

1. Implicitly add an id if none exists, based on the text content of the header, in the front-end framework. We might need to do something to make the link hashes actually work since the id might not exist on page load.

2. Implicitly add ids that don't exist as part of the distill pipeline publish process.

3. Provide a helper script to rewrite your source html locally with heading ids.

Option (3) feels gross. I would vote for (1) if possible, (2) if that becomes too weird with the timing of page load and adding ids with javascript and interactions with the url hash. Both (1) and (2) are still brittle (in that if an author changes the text of a header, the link id will change) but it allows authors to fix broken links by explicitly adding the old id to a heading if they want to change the text. Still a little brittle, but there is a fix available. Still allows for a state where links exist to old and new ids of headings if someone forgets to add the old id for some time and then updates it, but that risk seems worth accepting for the convenience to authors of not having to id every heading by hand.