markdown-it-anchor-sections

Markdown headers wrapped in semantic sections with anchor tags.

Wrap markdown content in <section> tags automatically, grouped by header level, and hoisting or creating an anchor tag on the section; perfect for Intersection Observers, scroll-spying, or semantic styling without manual markup.

# Introduction

Hello world.

## Details

More info here.

renders to:

<section id="introduction">
	<h1>Introduction</h1>
	<p>Hello world.</p>
	<section id="details">
		<h2>Details</h2>
		<p>More info here.</p>
	</section>
</section>

The problem

Modern web layouts often require grouping content into logical blocks—for example, to trigger animations as sections enter the viewport or to build sticky navigation that knows which part of the page you're reading.

Markdown is inherently flat. While you can manually wrap blocks in <div> or <section> tags, it breaks the readability of the raw text and is prone to errors. markdown-it-anchor-sections bridges the gap by treating your header hierarchy as the source of truth for your document's structure.

Features

• Hierarchical nesting — lower-level headers (like h3) are automatically nested within higher-level sections (like h2)
• Attribute-aware — works seamlessly with markdown-it-attrs sections inherit the same IDs as their headers
• Semantic HTML — produces clean, valid <section> structures that reflect your content's outline
• Zero configuration — works out of the box with sensible defaults
• Lightweight — tiny footprint with no external dependencies

Installation

Install via your preferred package manager:

yarn add markdown-it-anchor-sections
npm install markdown-it-anchor-sections
pnpm add markdown-it-anchor-sections
bun add markdown-it-anchor-sections

Usage

import md from "markdown-it";
import anchorSections from "markdown-it-anchor-sections";

const parser = md().use(anchorSections);

const src = `
# First header
lorem ipsum

## Second header
dolor sit amet
`;

console.log(parser.render(src));

With attributes

If you use markdown-it-attrs before this plugin, the generated <section> tags will inherit the id applied to the headers and retain any other attributes on the header.

import md from "markdown-it";
import attrs from "markdown-it-attrs";
import anchorSections from "markdown-it-anchor-sections";

const parser = md().use(attrs).use(anchorSections);

Markdown:

# Great stuff {.jumbotron #intro}

lorem ipsum

Output:

<section id="intro">
	<h1 class="jumbotron">Great stuff</h1>
	<p>lorem ipsum</p>
</section>

How it works

1. Iterates through the token stream generated by markdown-it.
2. When a header token is encountered, it identifies its level (1–6).
3. Closes any open sections of the same or lower level.
4. Opens a new <section> tag.
5. If the header has attributes (classes, IDs, etc.), they are copied to the opening <section> tag.
6. Automatically closes all remaining tags at the end of the document.

License

Apache 2.0 © Cassondra Roberts

Inspiration

This project was inspired by markdown-it-header-sections.