Adding a sticky table of contents to an Astro blog

Long blog posts need wayfinding. A sticky table of contents that tracks where you are as you scroll is one of the most useful navigational additions you can make to a reading experience. This post covers how I built one for this site in a way that generates the heading list at build time rather than in client-side JavaScript. The build-time approach means no DOM inspection, no flash of missing content, and no layout shift.

How Astro provides headings

When you render a markdown content entry with render() from astro:content, it returns both the Content component and a headings array. Each item has the shape:

1
{
2
  depth: number;   // 1–6, matching the h1–h6 level
3
  slug: string;    // URL-safe id matching the id Astro sets on the element
4
  text: string;    // Plain text content of the heading
5
}

Crucially, the slug values in this array match the id attributes Astro’s Markdown renderer writes onto the heading elements in the output HTML. That means you can generate anchor links at build time without any DOM inspection.

Passing headings to the layout

In the dynamic blog route, destructure headings from render() and forward it to the layout:

1
const { post } = Astro.props;
2
const { Content, headings } = await render(post);

1
<MarkdownPostLayout frontmatter={post.data} postId={post.id} headings={headings}>
2
  <Content />
3
</MarkdownPostLayout>

Filtering and rendering the ToC at build time

In the layout’s frontmatter, filter to h2 and h3 — deep nesting beyond that makes the sidebar more confusing than helpful. Only render the sidebar at all if there are at least two items:

1
---
2
const { frontmatter, postId, headings = [] } = Astro.props;
3
const tocHeadings = (headings as { depth: number; slug: string; text: string }[])
4
  .filter((h) => h.depth === 2 || h.depth === 3);
5
---

The sidebar markup is static HTML emitted at build time:

1
{tocHeadings.length > 1 && (
2
  <aside class="post__sidebar" aria-label="Table of contents">
3
    <nav class="toc">
4
      <p class="toc__heading">On this page</p>
5
      <ol class="toc__list">
6
        {tocHeadings.map((h) => (
7
          <li class={`toc__item toc__item--h${h.depth}`}>
8
            <a class="toc__link" href={`#${h.slug}`}>{h.text}</a>
9
          </li>
10
        ))}
11
      </ol>
12
    </nav>
13
  </aside>
14
)}

No document.createElement, no innerHTML, no flash of missing content. <ol> is used rather than <ul> because the heading sequence in a document is ordered from top to bottom, not an unordered collection.

Layout structure

The sidebar sits alongside the post content in a CSS grid. The two-column layout only activates at wide viewports — below 1280px the sidebar is hidden and the post reads as a single column as usual:

1
.post__layout {
2
  margin: 0 auto;
3

4
  @media (min-width: 1280px) {
5
    display: grid;
6
    grid-template-columns: minmax(0, 68ch) 260px;
7
    gap: 4rem;
8
    align-items: start;
9
    justify-content: center;
10
  }
11
}
12

13
.post__layout__content {
14
  min-width: 0;
15
}
16

17
.post__sidebar {
18
  display: none;
19

20
  @media (min-width: 1280px) {
21
    display: block;
22
    align-self: start;
23
    position: sticky;
24
    top: 6rem;
25
    max-height: calc(100vh - 8rem);
26
    overflow-y: auto;
27
  }
28
}

minmax(0, 68ch) prevents the content column from overflowing its grid cell on narrow-ish wide viewports. align-self: start is required for position: sticky to work on a grid item — without it the item stretches to the full column height and sticky has nothing to scroll within.

Sticky sidebar

position: sticky; top: 6rem on .post__sidebar keeps the ToC in view as the reader scrolls. max-height: calc(100vh - 8rem) with overflow-y: auto ensures very long tables of contents don’t overflow the viewport.

Active section highlighting with IntersectionObserver

The ToC links are plain anchor links in the static HTML. Highlighting the currently-visible section requires a small amount of client-side JavaScript. IntersectionObserver is the right tool — it fires without scroll event listeners and has good performance characteristics:

1
const tocLinks = document.querySelectorAll<HTMLAnchorElement>('.toc__link');
2
if (tocLinks.length) {
3
  const setActive = (id: string) => {
4
    tocLinks.forEach((l) =>
5
      l.classList.toggle('is-active', l.getAttribute('href') === `#${id}`)
6
    );
7
  };
8

9
  const headingEls = document.querySelectorAll<HTMLElement>(
10
    '.post__content h2, .post__content h3'
11
  );
12
  const obs = new IntersectionObserver(
13
    (entries) => {
14
      for (const entry of entries) {
15
        if (entry.isIntersecting) {
16
          setActive(entry.target.id);
17
          break;
18
        }
19
      }
20
    },
21
    { rootMargin: '0px 0px -80% 0px' }
22
  );
23
  headingEls.forEach((h) => obs.observe(h));
24
}

rootMargin: '0px 0px -80% 0px' shrinks the observable area to the top 20% of the viewport. A heading becomes “active” as soon as it enters that band, which means the active link reflects the section the reader just reached rather than a section far below the current scroll position.

Adding the script

The IntersectionObserver code lives in MarkdownPostLayout.astro inside a plain <script> tag with no attributes:

1
<script>
2
  // ... ToC observer and other layout scripts
3
</script>

Astro treats an unattributed <script> tag as a bundled module script. It processes it through the build pipeline, deduplicates it across all pages that use the layout, and defers it automatically. TypeScript is supported without any extra configuration. No is:inline or type="module" attribute is needed.

Styles

h2 and h3 items are visually distinguished by indentation and font size. The toc__heading element uses the site’s pink accent as both its text colour and a top border, tying it visually to the active link indicator. The active state uses the pink accent on text, a left border, and a faint pink background tint — consistent with other interactive indicators on the site:

1
.toc__heading {
2
  font-family: 'Barlow Condensed', sans-serif;
3
  font-size: 0.75rem;
4
  font-weight: 700;
5
  text-transform: uppercase;
6
  letter-spacing: 0.1em;
7
  color: var(--color-pink);
8
  padding-top: 0.75rem;
9
  border-top: 2px solid var(--color-pink);
10
  margin-bottom: 0.75rem;
11
}
12

13
.toc__link {
14
  display: block;
15
  font-size: 0.9375rem;
16
  line-height: 1.4;
17
  color: var(--color-muted);
18
  text-decoration: none;
19
  padding: 0.45rem 0.5rem 0.45rem 0.75rem;
20
  border-left: 2px solid transparent;
21
  border-radius: 0 3px 3px 0;
22
  transition: color 0.15s ease, border-color 0.15s ease, background-color 0.15s ease;
23

24
  &:hover {
25
    color: var(--color-ink);
26
    background-color: var(--color-surface);
27
  }
28

29
  &.is-active {
30
    color: var(--color-pink);
31
    border-left-color: var(--color-pink);
32
    background-color: rgba(232, 0, 106, 0.06);
33
  }
34
}
35

36
.toc__item--h3 .toc__link {
37
  padding-left: 1.5rem;
38
  font-size: 0.875rem;
39
}

The result

Posts with two or more h2/h3 headings get a sticky sidebar that renders as static HTML, requires no JavaScript to display, and uses a small IntersectionObserver to keep the active link accurate as the reader scrolls. Posts with fewer headings render without a sidebar, using the full column width.