rehype-slug

plugin to add `id` attributes to headings

Showing:

Popularity

Downloads/wk

59.8K

GitHub Stars

27

Maintenance

Last Commit

1mo ago

Contributors

2

Package

Dependencies

7

License

MIT

Type Definitions

Built-In

Tree-Shakeable

No?

Categories

Readme

rehype-slug

Build Coverage Downloads Size Sponsors Backers Chat

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:

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.

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

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100