rehype-slug

rehype-slug is a plugin for the unified/rehype ecosystem that automatically adds id attributes to HTML headings (h1 through h6) that don’t already have one. It generates each id from the heading’s text content using the same slugging algorithm GitHub uses on its own rendered markdown, via the github-slugger dependency, so anchors line up with how GitHub displays the same content.

The plugin operates directly on the hast (HTML AST) tree produced by rehype, visiting every element node and checking whether it’s a heading lacking an id. It’s commonly paired with rehype-autolink-headings, which adds clickable anchor links back to the ids this plugin creates — together they power the “click to copy link” heading UX found on many documentation sites and markdown-to-HTML pipelines, including MDX-based static site generators.

What You Get

• Automatic id generation for every heading level (h1-h6) that lacks one
• GitHub-compatible slugs via the github-slugger dependency, so anchors match GitHub-rendered markdown
• An optional prefix option to namespace generated ids
• Full TypeScript types shipped with the package, with no separate @types install needed

Common Use Cases

• Adding deep-linkable anchors to long-form documentation pages
• Powering “copy link to heading” UI in docs sites and blogs
• Building a table of contents that links to in-page headings
• Ensuring markdown-rendered headings get consistent, predictable ids across a site

Under The Hood

Architecture

rehype-slug is a single-file plugin (lib/index.js) exporting a default factory function that returns a unified transformer. The transformer walks the hast tree with unist-util-visit, uses hast-util-heading-rank to detect heading elements and hast-util-to-string to extract their text, then assigns ids through a module-scoped GithubSlugger instance that gets reset at the start of every run. There’s no internal layering beyond this — the interesting architecture lives in the small set of well-established unified-ecosystem utilities it composes rather than in custom abstractions of its own. The shared, reset-per-run slugger instance is a minor design note worth flagging for anyone processing multiple files concurrently in the same process.

Tech Stack

Dependencies are exclusively other unified/rehype/hast ecosystem packages (github-slugger, hast-util-heading-rank, hast-util-to-string, unist-util-visit, plus @types/hast), and the package is published as ESM-only ("type": "module"). Source is plain JavaScript annotated with JSDoc types rather than compiled TypeScript; tsc --build is used only to emit declaration files and check types, not to transpile the runtime code. Tooling is xo (an ESLint preset) with Prettier for style, remark-cli with remark-preset-wooorm for linting the README itself, type-coverage to enforce fully-typed JSDoc, and c8 for coverage — no bundler is needed since it ships as a tiny, dependency-thin ESM module.

Code Quality

Tests live in a single test.js run via Node’s built-in test runner (node:test), covering the public API shape, default heading-id behavior, and the prefix option, with c8 --100 --check-coverage enforcing full statement coverage as part of the test script. Type safety is enforced strictly through type-coverage at 100%, and xo/Prettier keep style consistent. CI workflow files aren’t visible in a shallow clone, but README badges reference an active GitHub Actions build and Codecov coverage tracking. Between full coverage enforcement, strict typing, and consistent linting, code quality is comprehensive for a package this size.

API Design The public API is a single default export with zero required configuration — .use(rehypeSlug) works immediately — and exactly one optional prefix string for namespacing. Types ship alongside the runtime code so consumers get editor autocomplete and type-checking without installing a separate @types package. Naming and usage conventions match sibling unified plugins (rehype-*, remark-*), so anyone already using the ecosystem has effectively no onboarding cost.