Package Exports

rehype-slug-custom-id
rehype-slug-custom-id/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (rehype-slug-custom-id) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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:

npm install rehype-slug-custom-id

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>
<h6>Custom ID Should Be Here {#custom-id}</h6>

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>
<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:

<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.

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