rehype-slug
!Buildbuild-badgebuild
!Coveragecoverage-badgecoverage
!Downloadsdownloads-badgedownloads
!Sizesize-badgesize
!Sponsorssponsors-badgecollective
!Backersbackers-badgecollective
!Chatchat-badgechatrehype plugin to add
id
s to headings.Contents
* [`unified().use(rehypeSlug[, options])`](#unifieduserehypeslug-options)
* [`Options`](#options)
What is this?
This package is a unified (rehype) plugin to addid
s to headings.
It looks for headings (so <h1>
through <h6>
) that do not yet have id
s
and adds id
attributes to them based on the text they contain.
The algorithm that does this is github-slugger
github-slugger, which
matches how GitHub works.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
id
s to headings in the AST.When should I use this?
This plugin is useful when you have relatively long documents and you want to be able to link to particular sections.A different plugin,
rehype-autolink-headings
rehype-autolink-headings, adds
links to these headings back to themselves, which is useful as it lets users
more easily link to particular sections.Install
This package is ESM onlyesm. In Node.js (version 16+), install with npm:npm install rehype-slug
In Deno with
esm.sh
esmsh:import rehypeSlug from 'https://esm.sh/rehype-slug@6'
In browsers with
esm.sh
esmsh:<script type="module">
import rehypeSlug from 'https://esm.sh/rehype-slug@6?bundle'
</script>
Use
Say we have the following fileexample.html
:<h1 id=some-id>Lorem ipsum</h1>
<h2>Dolor sit amet 😪</h2>
<h3>consectetur & adipisicing</h3>
<h4>elit</h4>
<h5>elit</h5>
…and our module
example.js
looks as follows:import {read} from 'to-vfile'
import {rehype} from 'rehype'
import rehypeSlug from 'rehype-slug'
const file = await rehype()
.data('settings', {fragment: true})
.use(rehypeSlug)
.process(await read('example.html'))
console.log(String(file))
…then running
node example.js
yields:<h1 id="some-id">Lorem ipsum</h1>
<h2 id="dolor-sit-amet-">Dolor sit amet 😪</h2>
<h3 id="consectetur--adipisicing">consectetur & adipisicing</h3>
<h4 id="elit">elit</h4>
<h5 id="elit-1">elit</h5>
API
This package exports no identifiers. The default export isrehypeSlug
api-rehype-slug.unified().use(rehypeSlug[, options])
Add id
s to headings.Parameters
options
(Options
api-options, optional)
— configuration
Returns
Transform (Transformer
unified-transformer).Options
Configuration (TypeScript type).Fields
prefix
(string
, default:''
)
— prefix to add in front of `id`s
Types
This package is fully typed with TypeScript. It exports the additional typeOptions
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-slug@^6
,
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 ofrehype-slug
can open you up to a cross-site scripting (XSS)xss
attack as it sets id
attributes on headings, which causes what is known
as “DOM clobbering”.
Please use rehype-sanitize
rehype-sanitize and see its
Example: headings (DOM clobbering)rehype-sanitize-example for information on
how to properly solve it.Related
— add links to headings with IDs back to themselves
Contribute
Seecontributing.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 conductcoc. By interacting with this repository, organization, or community you agree to abide by its terms.