Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time
December 23, 2021 18:00
October 22, 2016 16:03
August 2, 2021 12:19
July 19, 2018 13:14
August 2, 2021 11:42
December 23, 2021 18:00
November 17, 2018 13:33
December 30, 2021 13:06
April 1, 2022 17:11
December 23, 2021 18:00


Build Coverage Downloads Size Sponsors Backers Chat

rehype plugin to add links to headings with ids back to themselves.


What is this?

This package is a unified (rehype) plugin to add links from headings back to themselves. It looks for headings (so <h1> through <h6>), that have id attributes, and injects a link to themselves. Similar functionality is applied by many places that render markdown. For example, when browsing this readme on GitHub or npm, an anchor is added to headings, which you can share to point people to a particular place in a document.

unified is a project that transforms content with abstract syntax trees (ASTs). rehype adds support for HTML to unified. hast is the HTML AST that rehype uses. This is a rehype plugin that adds links to headings in the AST.

When should I use this?

This plugin is useful when you have relatively long documents, where you want users to be able to link to particular sections, and you already have id attributes set on all (or certain?) headings.

A different plugin, rehype-slug, adds ids to headings. When a heading doesn’t already have an id attribute, it creates a slug from it, and adds that as the id attribute. When using both plugins together, all headings (whether explicitly with a certain id or automatically with a generate one) will get a link back to themselves.


This package is ESM only. In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:

npm install rehype-autolink-headings

In Deno with

import rehypeAutolinkHeadings from ''

In browsers with

<script type="module">
  import rehypeAutolinkHeadings from ''


Say we have the following file example.html:

<h1 id=some-id>Lorem ipsum</h1>
<h2>Dolor sit amet 😪</h2>
<h3>consectetur &amp; adipisicing</h3>

And our module example.js looks as follows:

import {read} from 'to-vfile'
import {rehype} from 'rehype'
import rehypeSlug from 'rehype-slug'
import rehypeAutolinkHeadings from 'rehype-autolink-headings'


async function main() {
  const file = await rehype()
    .data('settings', {fragment: true})
    .process(await read('example.html'))


Now, running node example.js yields:

<h1 id="some-id"><a aria-hidden="true" tabindex="-1" href="#some-id"><span class="icon icon-link"></span></a>Lorem ipsum</h1>
<h2 id="dolor-sit-amet-"><a aria-hidden="true" tabindex="-1" href="#dolor-sit-amet-"><span class="icon icon-link"></span></a>Dolor sit amet 😪</h2>
<h3 id="consectetur--adipisicing"><a aria-hidden="true" tabindex="-1" href="#consectetur--adipisicing"><span class="icon icon-link"></span></a>consectetur &#x26; adipisicing</h3>
<h4 id="elit"><a aria-hidden="true" tabindex="-1" href="#elit"><span class="icon icon-link"></span></a>elit</h4>
<h5 id="elit-1"><a aria-hidden="true" tabindex="-1" href="#elit-1"><span class="icon icon-link"></span></a>elit</h5>

👉 Note: observe that from the <h2> on, automatic ids are generated. This is done by rehype-slug. Without rehype-slug, those headings would not be linked.


This package exports no identifiers. The default export is rehypeAutolinkHeadings.

unified().use(rehypeAutolinkHeadings[, options])

Add links to headings with ids back to themselves.

👉 Note: this plugin operates on headings that have id attributes. You can use rehype-slug to automatically generate ids for headings.


Configuration (optional).


How to create links (string, default: 'prepend').

  • 'prepend' — inject link before the heading text
  • 'append' — inject link after the heading text
  • 'wrap' — wrap the whole heading text with the link
  • 'before' — insert link before the heading
  • 'after' — insert link after the heading

👉 Note: options.content is ignored when the behavior is wrap, is ignored when the behavior is prepend, append, or wrap.

Attributes to set on the link (Properties, optional). Defaults to {ariaHidden: true, tabIndex: -1} when in 'prepend' or 'append' mode, and {} otherwise.


hast nodes to insert in the link (Function|Node|Children). By default, a <span class="icon icon-link"></span> is used.

When a function is given, it’s called with the current heading (Element) and should return one or more nodes.

👉 Note: this option is ignored when the behavior is wrap.

hast node to wrap the heading and link with (Function|Node, optional). There is no default.

When a function is given, it’s called with the current heading (Element) and should return a hast node.

👉 Note: this option is ignored when the behavior is prepend, append, or wrap


Test to define which heading elements are linked. Any test that can be given to hast-util-is-element is supported. The default (no test) is to link all headings with an id attribute.

Can be used to link only <h1> through <h3> (with ['h1', 'h2', 'h3']), or for example all except <h1> (with ['h2', 'h3', 'h4', 'h5', 'h6']). A function can be given to do more complex things.


Example: different behaviors

This example shows what each behavior generates by default.

import {rehype} from 'rehype'
import rehypeAutolinkHeadings from 'rehype-autolink-headings'


async function main() {
  const behaviors = ['prepend', 'append', 'wrap', 'before', 'after']
  let index = -1
  while (++index < behaviors.length) {
    const behavior = behaviors[index]
        await rehype()
          .data('settings', {fragment: true})
          .use(rehypeAutolinkHeadings, {behavior})
          .process('<h1 id="' + behavior + '">' + behavior + '</h1>')


<h1 id="prepend"><a aria-hidden="true" tabindex="-1" href="#prepend"><span class="icon icon-link"></span></a>prepend</h1>
<h1 id="append">append<a aria-hidden="true" tabindex="-1" href="#append"><span class="icon icon-link"></span></a></h1>
<h1 id="wrap"><a href="#wrap">wrap</a></h1>
<a href="#before"><span class="icon icon-link"></span></a><h1 id="before">before</h1>
<h1 id="after">after</h1><a href="#after"><span class="icon icon-link"></span></a>

Example: content

The following example passes content as a function, to generate an accessible description of each link.

import {rehype} from 'rehype'
import rehypeAutolinkHeadings from 'rehype-autolink-headings'
import {toString} from 'hast-util-to-string'
import {h} from 'hastscript'


async function main() {
  const file = await rehype()
    .data('settings', {fragment: true})
    .use(rehypeAutolinkHeadings, {
      content(node) {
        return [
          h('span.visually-hidden', 'Read the “', toString(node), '” section'),
          h('span.icon.icon-link', {ariaHidden: 'true'})
    .process('<h1 id="xxx">xxx</h1>')



<h1 id="xxx"><a aria-hidden="true" tabindex="-1" href="#xxx"><span class="visually-hidden">Read the “xxx” section</span><span class="icon icon-link" aria-hidden="true"></span></a>xxx</h1>

Example: group

The following example passes group as a function, to dynamically generate a differing element that wraps the heading.

import {rehype} from 'rehype'
import rehypeAutolinkHeadings from 'rehype-autolink-headings'
import {h} from 'hastscript'


async function main() {
  const file = await rehype()
    .data('settings', {fragment: true})
    .use(rehypeAutolinkHeadings, {
      behavior: 'before',
      group(node) {
        return h('.heading-' + node.tagName.charAt(1) + '-group')
    .process('<h1 id="xxx">xxx</h1>')



<div class="heading-1-group"><a href="#xxx"><span class="icon icon-link"></span></a><h1 id="xxx">xxx</h1></div>


This package is fully typed with TypeScript. It exports an Options type, which specifies the interface of the accepted options.


Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, and 16.0+. Our projects sometimes work with older versions, but this is not guaranteed.

This plugin works with rehype-parse version 1+, rehype-stringify version 1+, rehype version 1+, and unified version 4+.


Use of rehype-autolink-headings can open you up to a cross-site scripting (XSS) attack if you pass user provided content in properties or content.

Always be wary of user input and use rehype-sanitize.



See in rehypejs/.github for ways to get started. See for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.


MIT © Titus Wormer