rehype-autolink-headings

rehype plugin to automatically add links to headings (h1-h6) that already have an ID.

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install rehype-autolink-headings

Use

Say we have the following file, fragment.html:

<h1>Lorem ipsum ????</h1>
<h2>dolor—sit—amet</h2>
<h3>consectetur &amp; adipisicing</h3>
<h4>elit</h4>
<h5>elit</h5>

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

import fs from 'node:fs'
import rehype from 'rehype'
import rehypeSlug from 'rehype-slug'
import rehypeAutolinkHeadings from 'rehype-autolink-headings'

const buf = fs.readFileSync('fragment.html')

rehype()
  .data('settings', {fragment: true})
  .use(rehypeSlug)
  .use(rehypeAutolinkHeadings)
  .process(buf)
  .then((file) => {
    console.log(String(file))
  })

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>

API

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

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

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

options

options.behavior

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

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

options.properties

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

options.content

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:

import {toString} from 'hast-util-to-string'
import {h} from 'hastscript'

// …

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

options.group

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.

import {h} from 'hastscript'

// …

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

options.test

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.

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

Functions can also be given to do more complex things!

Security

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.

Related

• rehype-slug — Add ids to headings
• rehype-highlight — Syntax highlight code blocks
• rehype-toc — Add a table of contents (TOC)

Contribute

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.

License

MIT © Titus Wormer

Current Tags

• 6.1.1                                ...           latest (4 years ago)

4 Versions

• 4.0.0                                ...           5 years ago
• 6.1.1                                ...           4 years ago
• 3.0.0                                ...           6 years ago
• 2.0.5                                ...           7 years ago