Project: remarkjs/remark-autolink-headings

Package: remark-autolink-headings@6.0.1

  1. Dependencies: 2·Dependents: 52
  2. remark plugin to automatically add links to headings
  1. remark 193
  2. unified 168
  3. markdown 135
  4. plugin 130
  5. mdast 88
  6. remark-plugin 73
  7. link 15
  8. automatic 2


Build Coverage Downloads Size Sponsors Backers Chat

remark plugin to automatically add links to headings.

This package integrates with remark-html (or alternatives). It is better to work with rehype, which is specifically made for HTML, and to use rehype-autolink-headings instead of this package.

This package works with headings that have IDs. One way to add IDs to headings is by using remark-slug before this plugin.


This plugin is ready for the new parser in remark (remarkjs/remark#536). No change is needed: it works exactly the same now as it did before!



npm install remark-autolink-headings


Say we have the following markdown file, example.md:

# Lorem ipsum 😪
## dolor—sit—amet
### consectetur & adipisicing
#### elit
##### elit

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

const fs = require('fs')
const unified = require('unified')
const markdown = require('remark-parse')
const html = require('remark-html')
const slug = require('remark-slug')
const headings = require('remark-autolink-headings')

const doc = unified()
  // Note that this module must be included after `remark-slug`.


Now, running node example yields:

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


remark().use(autolinkHeadings[, options])

Automatically add links to headings.


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']}

If behavior is wrap, then content is ignored.

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

const toString = require('mdast-util-to-string')
const 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 (Node) and should return a hast node.

const h = require('hastscript')

// …

function group(node) {
  return h('div.heading-' + node.depth + '-group')


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

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


See contributing.md in remarkjs/.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 © Ben Briggs