How the Dynamic Table of Contents Feature Was Built on Medium
The journey of an idea from prototype to production.
1Identifying a User Need
The Medium team noticed that a popular Chrome extension, which added a table of contents to articles, was widely used by their audience. This signaled a clear user demand, prompting the team to take action.
2Starting with a Simple Copy
Initially, the team decided to replicate the functionality of the existing Chrome extension. The extension added a new option to the editor's popup menu. While this was a straightforward starting point, it had significant limitations.
3Drawbacks of a Static Solution
The extension inserted a static table of contents into the article body. This clashed with Medium's revision model and could disrupt the reading experience. Additionally, the table wasn't dynamic, so it became outdated with article updates.
4User Experience Issues
The extension always placed the table of contents at the top of the article. Users had to scroll back up after jumping to a section, and the abrupt transitions felt jarring. These flaws highlighted the need for a better solution.
5Pursuing a Dynamic Solution
The team aimed to create a dynamic table of contents that wouldn't require manual updates from writers. The goal was to generate the table at render time by analyzing the article's current content.
6Technical Challenges
Medium's article model was complex, built from a series of revisions layered on top of each other. To accurately generate a table of contents, the team needed to analyze the final rendered version of the article.
7The Solution: Render-Time Generation
Instead of navigating the intricate revision model, the team chose to analyze the article's final state at render time. This approach mirrored the Chrome extension's functionality but was more dynamic and sustainable.
8Analyzing Headings
The table of contents was built using H2, H3, and H4 headings. H2 and H3 headings became top-level entries, while H4 headings nested under the nearest top-level heading. This structure allowed for intuitive navigation.
9Outcome and User Experience
The dynamic table of contents eliminated the need for manual updates by writers. Users could access the table from anywhere in the article and enjoy a seamless navigation experience, enhancing overall readability.