rehype-autolink-headings

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[rehype][] plugin to add links from headings back to themselves.

Contents

* What is this?
* When should I use this?
* Install
* Use
* API
* [unified().use(rehypeAutolinkHeadings[, options])](#unifieduserehypeautolinkheadings-options)
* Behavior
* Build
* BuildProperties
* Options
* Examples
* Example: different behaviors
* Example: building content with hastscript
* Example: passing content from a string of HTML
* Example: group
* Types
* Compatibility
* Security
* Related
* Contribute
* License

What is this?

This package is a [unified][] ([rehype][]) plugin to add links from headings
back to themselves.
It looks for headings (so

through

) that have id properties,
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
properties set on all (or certain?) headings.

A different plugin, [rehype-slug][rehype-slug], adds ids to headings.
When a heading doesn’t already have an id property, it creates a slug from
it, and adds that as the id property.
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.

Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

``sh
npm install rehype-autolink-headings
`

In Deno with [esm.sh][esmsh]:

`js
import rehypeAutolinkHeadings from 'https://esm.sh/rehype-autolink-headings@7'
`

In browsers with [esm.sh][esmsh]:

`html

`

Use

Say we have the following file example.html:

`html


Solar System

Formation and evolution

Structure and composition

Orbits

Composition

Distances and scales

Interplanetary environment

…

`

…and our module example.js contains:

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

const file = await rehype()
.data('settings', {fragment: true})
.use(rehypeSlug)
.use(rehypeAutolinkHeadings)
.process(await read('example.html'))

console.log(String(file))
`

…then running node example.js yields:

`html


Solar System

Formation and evolution

Structure and composition

Orbits

Composition

Distances and scales

Interplanetary environment

…

`

API

This package exports no identifiers.
The default export is [rehypeAutolinkHeadings][api-rehype-autolink-headings].

$3

Add links from headings back to themselves.

###### Parameters

* options ([Options][api-options], optional)
— configuration

###### Returns

Transform ([Transformer][unified-transformer]).

###### Notes

This plugin only applies to headings with ids.
Use rehype-slug to generate ids for headings that don’t have them.

Several behaviors are supported:

* 'prepend' (default) — 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

$3

Behavior (TypeScript type).

###### Type

`ts
type Behavior = 'after' | 'append' | 'before' | 'prepend' | 'wrap'
`

$3

Generate content (TypeScript type).

###### Parameters

* element ([Element][hast-element])
— current heading

###### Returns

Content ([Array][hast-node] or Node).

$3

Generate properties (TypeScript type).

###### Parameters

* element ([Element][hast-element])
— current heading

###### Returns

Properties ([Properties][hast-properties]).

$3

Configuration (TypeScript type).

###### Fields

* behavior ([Behavior][api-behavior], default: 'prepend')
— how to create links
* content ([Array][hast-node], Node, or [Build][api-build],
default: if 'wrap' then undefined, otherwise equivalent of
)
— content to insert in the link;
if behavior is 'wrap' and Build is passed, its result replaces the
existing content, otherwise the content is added after existing content
* group ([Array][hast-node], Node, or [Build][api-build],
optional)
— content to wrap the heading and link with, if behavior is 'after' or
'before'
* headingProperties ([BuildProperties][api-build-properties] or
[Properties][hast-properties], optional)
— extra properties to set on the heading
* properties ([BuildProperties][api-build-properties] or
[Properties][hast-properties], default:
{ariaHidden: true, tabIndex: -1} if 'append' or 'prepend', otherwise
undefined)
— extra properties to set on the link when injecting
* test ([Test][hast-util-is-element-test], optional)
— extra test for which headings are linked

Examples

$3

This example shows what each behavior generates by default.

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

const behaviors = ['after', 'append', 'before', 'prepend', 'wrap']
let index = -1
while (++index < behaviors.length) {
const behavior = behaviors[index]
console.log(
String(
await rehype()
.data('settings', {fragment: true})
.use(rehypeAutolinkHeadings, {behavior})
.process('

' + behavior + '

')
)
)
}
`

Yields:

`html


after

append

before

prepend

wrap

`

$3

The following example passes options.content as a function, to generate an
accessible description specific to each link.
It uses [hastscript][hastscript] to build nodes.

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

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('

Pluto

')

console.log(String(file))
`

Yields:

`html


Read the “Pluto” sectionPluto


`

$3

The following example passes content as nodes.
It uses [hast-util-from-html-isomorphic][hast-util-from-html-isomorphic] to
build nodes from a string of HTML.

`js
/**
* @typedef {import('hast').ElementContent} ElementContent
*/

import {fromHtmlIsomorphic} from 'hast-util-from-html-isomorphic'
import {rehype} from 'rehype'
import rehypeAutolinkHeadings from 'rehype-autolink-headings'

const file = await rehype()
.data('settings', {fragment: true})
.use(rehypeAutolinkHeadings, {
content: /* @type {Array} / (
fromHtmlIsomorphic(
'',
{fragment: true}
).children
)
})
.process('

Makemake

')

console.log(String(file))
`

Yields:

`html


Makemake


`

$3

The following example passes group as a function, to dynamically generate a
differing element that wraps the heading.
It uses [hastscript][hastscript] to build nodes.

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

const file = await rehype()
.data('settings', {fragment: true})
.use(rehypeAutolinkHeadings, {
behavior: 'before',
group(node) {
return h('.heading-' + node.tagName.charAt(1) + '-group')
}
})
.process('

Ceres

')

console.log(String(file))
`

Yields:

`html



`

Types

This package is fully typed with [TypeScript][].
It exports the additional types
[Behavior][api-behavior],
[Build][api-build],
[BuildProperties][api-build-properties], and
[Options][api-options].

Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
rehype-autolink-headings@^7, compatible with Node.js 16.

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

Security

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

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

Related

* [rehype-slug][rehype-slug]
— add ids to headings
* rehype-highlight
— apply syntax highlighting to code blocks
* rehype-toc
— add a table of contents (TOC)

Contribute

See [contributing.md][contributing] in [rehypejs/.github][health] for ways
to get started.
See [support.md`][support] for ways to get help.

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

License

[MIT][license] © [Titus Wormer][author]

[build-badge]: https://github.com/rehypejs/rehype-autolink-headings/workflows/main/badge.svg

[build]: https://github.com/rehypejs/rehype-autolink-headings/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/rehypejs/rehype-autolink-headings.svg

[coverage]: https://codecov.io/github/rehypejs/rehype-autolink-headings

[downloads-badge]: https://img.shields.io/npm/dm/rehype-autolink-headings.svg

[downloads]: https://www.npmjs.com/package/rehype-autolink-headings

[size-badge]: https://img.shields.io/bundlejs/size/rehype-autolink-headings

[size]: https://bundlejs.com/?q=rehype-autolink-headings

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/rehypejs/rehype/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[health]: https://github.com/rehypejs/.github

[contributing]: https://github.com/rehypejs/.github/blob/main/contributing.md

[support]: https://github.com/rehypejs/.github/blob/main/support.md

[coc]: https://github.com/rehypejs/.github/blob/main/code-of-conduct.md

[license]: license

[author]: https://wooorm.com

[hast-element]: https://github.com/syntax-tree/hast#element

[hast-node]: https://github.com/syntax-tree/hast#nodes

[hast-util-is-element-test]: https://github.com/syntax-tree/hast-util-is-element#test

[hast-properties]: https://github.com/syntax-tree/hast#properties

[hastscript]: https://github.com/syntax-tree/hastscript

[hast-util-from-html-isomorphic]: https://github.com/syntax-tree/hast-util-from-html-isomorphic

[rehype]: https://github.com/rehypejs/rehype

[rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize

[typescript]: https://www.typescriptlang.org

[unified]: https://github.com/unifiedjs/unified

[unified-transformer]: https://github.com/unifiedjs/unified#transformer

[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[rehype-slug]: https://github.com/rehypejs/rehype-slug

[api-behavior]: #behavior

[api-build]: #build

[api-build-properties]: #buildproperties

[api-options]: #options

[api-rehype-autolink-headings]: #unifieduserehypeautolinkheadings-options