How we built the new Table of Contents feature

Summary

Medium built a new Table of Contents feature after an existing Chrome extension demonstrated demand, while its approach of inserting a static list into post content created revision, maintenance, navigation, and reading-experience problems. The shipped implementation derives a nested list from the rendered post body at runtime: H2 and H3 become top-level entries, H4 headings nest beneath the latest top-level heading, and lead title, subtitle, and kicker are excluded. It appears as a right-margin indicator that scrolls with the reader, highlights the current heading, supports smooth scrolling, and uses a sliding window for posts with many headings. Full-width images receive a translucent background, one-heading posts hide the feature, and mobile needs a separate solution because desktop indicators overlap content; the feature took a couple of days, mostly for UX testing and design iteration.

Takeaways

1. 1

   Generating the table of contents at render time keeps it synchronized with revisions and avoids adding index content to the post itself.

2. 2

   The desktop interface uses long and short heading indicators, current-heading highlighting, smooth scrolling, a translucent background over full-width images, and a sliding window for posts with many headings.

3. 3

   Mobile requires a separate design because the desktop indicators overlap the narrower post content; Medium also states that table-of-contents scrolling does not affect valid reads or earnings.