Add the ability to permalink all chapter headings and figures

[rviscomi]

@HTTPArchive/developers

All headings in the chapter should have a unique ID to which we can deep link. It would also be nice if a clickable link icon appeared on hover so users can copy the URL.

In addition, figures like charts and data tables should be able to be deep linked. Since the Almanac is a reference document, we should expect and support third party websites to link citations to specific figures. Ideally, deep linking figures should be built into the process for #67.

If not statically baked into the markup, we could consider implementing this as a JS function at runtime.

[tyohan]

I'll work on this.

[rviscomi]

Thanks @tyohan!

One thing I forgot to mention is that when a user clicks on a deep link into the chapter, the page must jump down to that section. So if the IDs are not baked into the markup the browser might not make the jump immediately on page load and our JS solution would have to parse the URL hash and scroll manually.

Which approach do you prefer: static markup or dynamic JS?

[tyohan]

I prefer to use static markup, so I'll make sure we can make this built in the process for #67 and other sections too. We can add JS function later for smooth scrolling if needed.

[rviscomi]

@tyohan as we wrap up the chapter page design, I had a thought about how we could implement the static markup approach for this issue. generate_chapters.py is a script that converts markdown into markup, based on mistune.

We could create a custom renderer similar to their Table of Contents example to take markdown headings and inject ID attributes into their markup.

For example, given something like ## Intro I'd expect it to generate <h2 id="intro">Intro</h2> and a corresponding table of contents.

WDYT?

[foxdavidj]

@rviscomi so essentially creating a slug for any given heading like so:

Zooming, scaling and rotating pages => zooming-scaling-and-rotating-pages

Sounds like a good idea to me.

[rviscomi]

Yes, exactly!

[foxdavidj]

Awesome. In case you run into some edge cases and want to see how others have done it, here's the function WP uses to "slugify" titles as reference

https://core.trac.wordpress.org/browser/tags/5.2.3/src/wp-includes/formatting.php#L2206

[rviscomi]

@tyohan FYI as part of @mikegeyser's investigation into #219 we decided to replace mistune with showdown. In a test of the new renderer I noticed that it's automatically generating IDs for headings. Sorry, I see that you've already started working on this.

@mikegeyser before fully committing to showdown can we verify that it supports this table of contents use case? We're looking for comparable functionality to mistune's TOC example.

[mikegeyser]

Hey @tyohan! I'm really sorry for the change, and if there's any wasted effort. We'll try to keep it minimal.

@rviscomi there seem to be some extensions, but they're really straight forward. It shouldn't be hard to write a small extension that produces exactly the desired output. I don't want to overload #222, could I do the work in a follow-up PR?

[rviscomi]

Oh, yeah, no need to implement this in #222.

I think @tyohan will continue to work on this feature using showdown instead. You can focus on migrating markdown tools.

Thanks for investigating the showdown extensions.

[tyohan]

@rviscomi @mikegeyser sorry missed this convo. Yes, I'm using the mistune table of content plugin to implement the content index in chapter page. Let me finish the chapter page first then later will see if we can convert it with showdown. I still need to work on next and previous button.

[mikegeyser]

@tyohan I think I've reimplemented the toc generation in #232. Would you mind taking a look and seeing if it's useful with what you've done?

[rviscomi]

The "permalink all chapter headings" part of this issue is resolved.

As for permalinking figures, what I've been doing is manually adding ID attributes to the figure elements. For example:

<figure id="fig1">
  <img>
  <figcaption>Figure 1. Foobar</figcaption>
</figure>

We could try to generate the fig IDs automatically in the generator but I think it'll be overkill. Would be cool though.

Given that, I think this issue is ready to be closed.