rehype-slug

rehype plugin to add ids to headings.

Install

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

npm install rehype-slug

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 slug from 'rehype-slug'

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

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

Now, running node example yields:

<h1 id="lorem-ipsum-">Lorem ipsum ????</h1>
<h2 id="dolorsitamet">dolor—sit—amet</h2>
<h3 id="consectetur--adipisicing">consectetur &#x26; adipisicing</h3>
<h4 id="elit">elit</h4>
<h5 id="elit-1">elit</h5>

API

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

`unified().use(rehypeSlug)`

Add id properties to h1-h6 headings that don’t already have one.

Uses github-slugger to create GitHub style ids.

Security

Use of rehype-slug can open you up to a cross-site scripting (XSS) attack as it sets id attributes on headings. In a browser, elements are retrievable by id with JavaScript and CSS. If a user injects a heading that slugs to an id you are already using, the user content may impersonate the website.

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

remark-slug — Add slugs to headings in markdown

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

Current Tags

5.0.1 ... latest (4 years ago)

3 Versions

5.0.1 ... 4 years ago
3.0.0 ... 5 years ago
2.0.3 ... 6 years ago