Article pages Table of Contents feature

[HesitantlyHuman]

Hi! I'm back again with another feature.

I've implemented a table of contents for the article pages, and figured I'd throw another quick PR, since that is listed on the roadmap.

Features and Changes

1. Added dynamic table of contents (TOC) which renders from the markdown headings and links to section headings.
2. Widened the content page to facilitate the width of the TOC and article. Set the TOC to hide when we reach a breakpoint.
3. Added support for changing the TOC nesting depth on a per article basis, to prevent generation of TOCs which are excessively large.
4. Added scrolling behavior for TOCs which are too long. The TOC will follow your current page position on scroll, but remains scrollable for navigation purposes. Added simple fade out styling to indicate when the TOC is in a scrolled position, since the scrollbar is hidden unless the TOC is hovered.
5. Added current position indicator and animation. This animation is generated and rendered client side, so that it can be reactive to page resizing or other content changes.

Known Issues

Because we are using remark-sectionize to wrap our content sections (so that we are able to track our current location in the article) client:load components with inline mdx imports will throw errors, since they are not able to properly locate the import. The simple fix is to do the import at the top of the mdx file, before any markdown headers. While I am personally fine with this fix, I know that this may be inconvenient for some.

Screenshots

Here are some quick screenshots so that you can see how the TOC looks and functions.

Here is how it looks on hover

If there are no headers, we allow the article to take the full width of the page

Simple example without nesting

Blog post 4 with nav_depth: 3 has a very long TOC. Here is it following your current position, with the fades

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
astro-sphere	❌ Failed (Inspect)			May 20, 2025 2:29am