Implementing sticky mobile navigation

The original mobile table of contents was a simple collapsible element that lived within the post content. This created several usability issues:

1. Users had no sense of how much content remained other than implying it based on the length of the browser scrollbar
2. Once you scrolled past the TOC, you lose the ability to quickly navigate to other sections of the post without scrolling back up to the inline TOC
3. Mobile users should have the exact same experience as desktop users in terms of navigation, and as of now the desktop experience was better (due to the sticky aside TOC)

Building the sticky header system

Design-wise, the component is relatively simple, since it only includes a chevron to indicate expansion state, a circular progress indicator that fills as you scroll, and a dynamic text showing the current section (or a combination of sections, if multiple are visible at the same time).

Live scroll highlighting sucks

One of the more interesting problems I encountered was how to handle the highlighting of sections as you scroll. Of course, this applies to both mobile and desktop versions, but in this update I changed the implementation of both.

A naive implementation of live scroll highlighting would simply use an IntersectionObserver() to watch for headers entering and exiting the viewport. The issue with this is that it doesn’t highlight anything if headers are no longer visible in your viewport, regardless of whether you’re in a section that “belongs” to a heading.

1
## Part 1
2
[500 lines of content]
3

4
## Part 2
5
[500 lines of content]

I used to rely on jakelow/remark-sectionize, a remarkjs/remark plugin that retroactively generates <section> tags based on the headers in the generated HTML. This would have done the following conversion:

1
# Forest elephants
2

3
## Introduction
4

5
In this section, we discuss the lesser known forest elephants.
6

7
## Habitat
8

9
Forest elephants do not live in trees but among them.

1
<section>
2
  <h1>Forest elephants</h1>
3
  <section>
4
    <h2>Introduction</h2>
5
    <p>In this section, we discuss the lesser known forest elephants.</p>
6
  </section>
7
  <section>
8
    <h2>Habitat</h2>
9
    <p>Forest elephants do not live in trees but among them.</p>
10
  </section>
11
</section>

However, this approach had pretty complicated issues involving section nesting and the fact that we didn’t have any control over its output other than by patching it. So, I decided to opt for a home-grown solution.

The concept of “jurisdictions”

The naming is interesting but I felt like it was the most intuitive to me. Basically, I created a system that assigns each heading a “territory” that extends from its position to the start of the next heading (or the end of the document):

123
function buildHeadingJurisdictions() {
124
  headingElements = Array.from(
125
    document.querySelectorAll('.prose h2, .prose h3, .prose h4, .prose h5, .prose h6')
126
  )
127

128
  jurisdictions = headingElements.map((heading, index) => {
129
    const nextHeading = headingElements[index + 1]
130
    return {
131
      id: heading.id,
132
      start: heading.offsetTop,
133
      end: nextHeading ? nextHeading.offsetTop : document.body.scrollHeight
134
    }
135
  })
136
}

1. First, we collect all heading elements (<h2> through <h6>) from the document’s prose content area using .querySelectorAll().
2. For each heading, we create a jurisdiction object that contains the heading’s id, the vertical position where this section begins (the heading’s offsetTop value, which we name start), and the vertical position where this section ends (the offsetTop of the next heading or the bottom of the document if it’s the last heading, which we name end).

This creates a map of “territories” that each heading controls. This is crucial for accurately tracking which jurisdictions are currently visible as the user scrolls, even when the actual heading element itself is no longer in view.

The decision to show all visible sections

One of the more interesting decisions I made was to display all sections as comma-separated within the mobile TOC’s unexpanded state. This manifests as follows:

1
## Part 1
2
[500 lines of content]
3

4
## Part 2
5
[500 lines of content]

The temptation is to implement a “smart” selection algorithm, perhaps showing the section with the most visible content, or the one closest to the viewport center, or to show the “deepest,” most specifically nested section. However, this creates numerous edge cases:

1. If you click to navigate to a short final section, it might never become the “primary” section because there isn’t enough content below it to scroll it to the top of the viewport.

2. As you scroll between sections, a “smart” selector might switch which section it considers primary at seemingly arbitrary points, creating a jarring experience.

3. When your viewport shows roughly equal amounts of two sections, any selection algorithm becomes essentially arbitrary.

By showing all visible sections, we give users complete awareness of their position in the document, eliminate the edge cases mentioned above, and create predictable behavior.

Progress indicator implementation

The circular progress indicator provides immediate visual feedback about reading progress without requiring any interaction:

216
  function updateProgressCircle() {
217
    if (!progressCircleElement) return
218
    const scrollableDistance =
219
      document.documentElement.scrollHeight - window.innerHeight
220
    const scrollProgress =
221
      scrollableDistance > 0
222
        ? Math.min(Math.max(window.scrollY / scrollableDistance, 0), 1)
223
        : 0
224
    progressCircleElement.style.strokeDashoffset = (
225
      PROGRESS_CIRCLE_CIRCUMFERENCE *
226
      (1 - scrollProgress)
227
    ).toString()
228
  }

The progress is calculated as a ratio of current scroll position to total scrollable distance, then applied as a stroke-dashoffset to create the filling effect.