Table of Contents Demo

Updated 2026-03-04
#showcase #navigation #vaultex #toc

The right sidebar in Vaultex automatically generates a table of contents from the post’s headings. This post has an intentionally deep heading structure to demonstrate active tracking, collapsing behavior, and multi-level nesting in the TOC panel.

How the TOC Works

The TOC is generated client-side by scanning all h2, h3, and h4 elements in the post content. As you scroll, an IntersectionObserver watches each heading — when a heading enters the viewport, its TOC entry gets the active class, highlighted with the accent color.

The depth is controlled by toc_depth in themes/vaultex/_config.yml:

1
2
3
sidebar_right:
  toc: true
  toc_depth: 3   # h2, h3, h4 included

Section One — Concepts

1.1 What Is a Table of Contents

A table of contents maps the headings in a document to clickable anchor links. Clicking a TOC entry scrolls the content to that heading using native smooth scrolling.

1.2 Why Active Tracking Matters

On long posts, active heading tracking tells you where you are in the document without requiring you to scroll up and look. It’s especially useful on posts with 10+ sections.

Hexo’s markdown renderer automatically assigns id attributes to headings based on their text. Special characters are stripped and spaces become hyphens:

1
2
## Hello World  →  id="hello-world"
## CSS & HTML   →  id="css-html"

Section Two — Configuration

2.1 Enabling the TOC

The TOC is enabled by default in Vaultex. It renders only on post layout pages — the homepage, archive, and category pages don’t show it.

2.2 Disabling Per-Post

Add toc: false to a post’s front matter to suppress the TOC for that specific post:

1
2
3
4
---
title: Short Note
toc: false
---

2.3 Controlling Depth

Setting toc_depth: 2 includes only h2 headings. Setting it to 6 includes everything down to h6. In practice, 3 is the sweet spot — deeper nesting often signals that a section should be its own post.

Section Three — Design Decisions

3.1 Right Sidebar Position

The TOC lives in the right sidebar rather than being anchored to the content area because it needs to be visible regardless of how far down the post you are. A floating sidebar doesn’t scroll with the content.

3.2 Mobile Behavior

On narrow screens, the right sidebar collapses. The TOC is accessible via the panel toggle button in the tab bar. On mobile, most users navigate linearly anyway, so the TOC is a secondary concern.

3.3 Scroll Offset

When a TOC link is clicked, the target heading needs to account for the fixed tab bar at the top. CSS scroll-margin-top handles this without JavaScript:

1
2
3
h2, h3, h4, h5, h6 {
  scroll-margin-top: calc(var(--tab-bar-height) + 1rem);
}

4.1 Breadcrumb Navigation

The tab bar doubles as a breadcrumb trail: Vault name → Category → Post title. On the homepage it shows the vault name and the homepage subtitle.

Below the TOC in the right sidebar, Vaultex shows related posts based on shared tags. The more tags two posts share, the higher the related-post score.

4.3 Tag Cloud

The tag cloud renders all tags used across the site with font sizes proportional to usage count. It appears at the bottom of the right sidebar on post pages.

Section Five — Accessibility

5.1 ARIA Roles

The TOC nav element has role="navigation" and aria-label="Table of contents". Each TOC link has an aria-current="true" attribute when its heading is active.

5.2 Focus Management

When the right sidebar is opened via keyboard, focus is moved into the panel. When it’s closed, focus returns to the toggle button.

A visually-hidden skip link at the top of the page lets screen reader and keyboard users jump directly to the main content without tabbing through the sidebars.

Conclusion

The table of contents is one of the features that makes reading long technical posts on Vaultex genuinely better than a plain Markdown preview. Scroll down to the next section to watch the active heading tracker update in real time.