# How the Dynamic Table of Contents Feature Was Built on Medium

The journey of an idea from prototype to production.

- **Source:** [Medium Engineering](https://medium.com/medium-eng)
- **Published:** 2026-07-23
- **Topic:** [Product Management](https://brifing.si/c/product)
- **Original article:** <https://medium.engineering/how-we-built-the-new-table-of-contents-feature-c3825d8c279d?source=rss----2817475205d3---4>
- **On Brifing:** https://brifing.si/s/0d2f248f-922f-4f3f-b369-b1b8feb677d2

## Identifying 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.

## Starting 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.

## Drawbacks 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.

## User 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.

## Pursuing 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.

## Technical 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.

## The 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.

## Analyzing 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.

## Outcome 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.

## Sources covering this story

- https://medium.engineering/how-we-built-the-new-table-of-contents-feature-c3825d8c279d?source=rss----2817475205d3---4 — 

---

_Summary written by Brifing from the original reporting. Copyright in the original article belongs to its publisher; read the full piece at the link above._