Project: rehypejs/rehype-autolink-headings

Package: rehype-autolink-headings@6.1.1

  1. Dependents: 0
  2. rehype plugin to add links to headings
  1. unified 178
  2. plugin 138
  3. html 121
  4. rehype 89
  5. rehype-plugin 60
  6. heading 25
  7. link 15


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 esm.sh:

import rehypeAutolinkHeadings from 'https://esm.sh/rehype-autolink-headings@6'

In browsers with esm.sh:

<script type="module">
  import rehypeAutolinkHeadings from 'https://esm.sh/rehype-autolink-headings@6?bundle'


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').

πŸ‘‰ Note: options.content is ignored when the behavior is wrap, options.group 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 contributing.md in rehypejs/.github for ways to get started. See support.md 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