rehype-slug-custom-id

rehype plugin to add ids to headings with the option for custom IDs.

Install

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

npm:

1npm install rehype-slug-custom-id

Use

Say we have the following file, fragment.html:

1<h1>Lorem ipsum 😪</h1>
2<h2>dolor—sit—amet</h2>
3<h3>consectetur &amp; adipisicing</h3>
4<h4>elit</h4>
5<h5>elit</h5>
6<h6>Custom ID Should Be Here {#custom-id}</h6>

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

1import fs from 'node:fs'
2import {rehype} from 'rehype'
3import slug from 'rehype-slug'
4
5const buf = fs.readFileSync('fragment.html')
6
7rehype()
8  .data('settings', {fragment: true})
9  .use(slug)
10  .process(buf)
11  .then((file) => {
12    console.log(String(file))
13  })

Now, running node example yields:

1<h1 id="lorem-ipsum-">Lorem ipsum 😪</h1>
2<h2 id="dolorsitamet">dolor—sit—amet</h2>
3<h3 id="consectetur--adipisicing">consectetur &#x26; adipisicing</h3>
4<h4 id="elit">elit</h4>
5<h5 id="elit-1">elit</h5>
6<h6 id="custom-id">Custom ID Should Be Here</h6>

API

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, or a custom ID if supplied like so:

1<h1>ID {#custom-id-here}</h1>

We support the following options for the plugin:

• enableCustomId: Boolean. Enable custom header IDs with {#id} (optional)
• maintainCase: Boolean. Maintains the case for markdown header (optional)
• removeAccents: Boolean. Remove accents from generated headings IDs (optional)

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.

Related

• rehype-slug — Add slugs to headings in html
• remark-slug — Add slugs to headings in markdown
• gatsby-remark-autolink-headers — Add slugs to headings in markdown for Gatsby