Project: rehypejs/rehype-autolink-headings

Package: rehype-autolink-headings@5.1.0

  1. Dependents: 32
  2. rehype plugin to add links to headings
  1. unified 173
  2. plugin 135
  3. html 112
  4. rehype 78
  5. rehype-plugin 54
  6. heading 26
  7. link 16


Build Coverage Downloads Size Sponsors Backers Chat

rehype plugin to automatically add links to headings (h1-h6).



npm install rehype-autolink-headings


Say we have the following file, fragment.html:

<h1>Lorem ipsum 😪</h1>
<h3>consectetur &amp; adipisicing</h3>

And our script, example.js, looks as follows:

var fs = require('fs')
var rehype = require('rehype')
var slug = require('rehype-slug')
var link = require('rehype-autolink-headings')

var doc = fs.readFileSync('fragment.html')

  .data('settings', {fragment: true})
  .process(doc, function(err, file) {
    if (err) throw err

Now, running node example yields:

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


Add links to headings (h1-h6) with an id.

Note: this plugin expects ids to already exist on headings. One way to add those automatically, is rehype-slug (see example).


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

Supplying wrap will ignore any value defined by the content option. Supplying prepend, append, or wrap will ignore the group option.


Extra properties to set on the link (Object?). Defaults to {ariaHidden: true, tabIndex: -1} when in 'prepend' or 'append' mode.


hast nodes to insert in the link (Function|Node|Children). By default, the following is used:

  type: 'element',
  tagName: 'span',
  properties: {className: ['icon', 'icon-link']},
  children: []

If behavior is wrap, then content is ignored.

If content is a function, it’s called with the current heading (Element) and should return one or more nodes:

var toString = require('hast-util-to-string')
var h = require('hastscript')

// …

function content(node) {
  return [
    h('span.visually-hidden', 'Read the “', toString(node), '” section'),
    h('span.icon.icon-link', {ariaHidden: true})

hast node to wrap the heading and link with (Function|Node), if behavior is before or after. There is no default.

If behavior is prepend, append, or wrap, then group is ignored.

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

var h = require('hastscript')

// …

function group(node) {
  return h('.heading-' + node.charAt(1) + '-group')


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