RHS table of contents

[Ola Rubaj]

Priority over #153

---

User story

A user can quickly eyeball the contents of the current page by looking at the table of contents (ToC) on the right-hand side. He can also quickly navigate to different sections of the current page by clicking on a section title in the ToC and see where he's currently at thanks to highlighting of the currently focused section.

Inspiration

Tailwind page: https://tailwindcss.com/docs/installation

Acceptance

• ToC on the right-hand side that lists all the headings of the current page
• subheadings of different levels should be accordingly indented
• ToC should always be visible (doesn't hide on scrolling)
• page should smooth-scroll to a given section upon clicking on its title in the ToC
• title of the currently focused section should be highlighted

References

Original issue: #93

[Rufus Pollock]

Notes from discussion on ~ 14 June 2022

---

Analaysis

Key features

• RHS table of contents shows content from current page (excluding the main/page heading??)
• Updates as we scroll the page to highlight
• Quesitons
  • What happens on non-markdown pages?
  • Can we disable toc generation?
  • How does this connect to generating "toc" for entire site?

Aside: does this connect with anchor links for headings - #99

Note this was supposed to include nice anchor hovers but not sure that was implemented - note that issue is "bad" as no acceptance criteria, description or anything!

Comment from Ola: have implemented colored hover which may be just as good UX.

Broken word wrapping bug

As per the closed issue #99, the rehype plugin rehype-autolink-headings added anchor tags to headings. However, since there was no behavior: wrap option set to it, the anchor tags were added next to the spans with heading's text, like so:

• rehype plug in added in april and everything fine
• ola tweaked plugin so that we can have behaviour to click on headings and update anchor
  • Added option behaviour: wrap so that heading text was inside anchor rather than sibling to it
• led to bug because ... (something in css of rehype or otherwise)
• fixed this by adding css in our globals

Now we have this in contentlayer.config:

[ rehypeAutolinkHeadings, { behavior: 'wrap' } ],

<h2 id="the-politics-and-economics-of-daos-crypto-and-blockchain" class="c-heading scroll-mt-16 cursor-pointer">
<a href="#the-politics-and-economics-of-daos-crypto-and-blockchain">
The politics and economics of DAOs, crypto and blockchain
</a>
</h2>

We used to have this:

[ rehypeAutolinkHeadings ],

<h2 id="the-politics-and-economics-of-daos-crypto-and-blockchain" class="c-heading scroll-mt-16 cursor-pointer">
  <a aria-hidden="true" tabindex="-1" href="#the-politics-and-economics-of-daos-crypto-and-blockchain"><span class="icon icon-link"></span></a>
  The politics and economics of DAOs, crypto and blockchain
</h2>

---

Brainstorming

How can we do this?

• Do we do this on page render or e.g. do this with javascript after page load? ✅ best to do on page render if we can unless really painful
• Pre-requisites
  • anchor-id generation for headings (autolink-headings should provide this) ✅ already part of rehype-autolink-headings
• We need the list of headings in the current page ...
  • How do we get this?
• How do other people do this?
  • How does tailwindcss.com https://github.com/tailwindlabs/tailwindcss.com do this?
    • https://github.com/tailwindlabs/tailwindcss.com/blob/8b9f69a93a5a1b055dc8c1dcfa06f5ca2863b89c/src/layouts/ContentsLayout.js
  • How does remark-toc do this https://github.com/remarkjs/remark-toc
    • Do we want this or rehype-toc (https://github.com/JS-DevTools/rehype-toc) (or mdast-util-toc)? ✅ We want to use rehype-toc. Why: we want to make use of the html that has already been converted by other rehype plugin: rehype-slug - which attaches ID's to headings (there are no id's attached by default after parsing raw markdown headings)
      • this way, the ToC crated by the rehype-toc has correct id's in hrefs, so you can actually click on them and be redirected to the corresponding heading in the html
  • NTS: how will this relate to getting table of contents for whole project?

Proposed solution

• rehype-toc to generate a toc as html or in the syntax tree

Options

• Use rehype autolink headings etc => we hve to do heading extraction in rehype after this as this is where slugs get generated
  • Why? quick
• parse the markdown ourselves (use existing remark tooling) and take care of adding slugs there (so don't use rehype-autolink-headings and rehype-toc)
  • Why do this?
  • Because we have more control over extraction of ToC and its use in the page

[Rufus Pollock]

@olayway one issue with making the heading itself into a link is that you can't have links in the heading ... (i think this is the reason most people have a hover effect with actual link item outside of the text e.g. on the left as an icon). Examples of this behaviour on the news page https://web3.lifeitself.us/notes/news