Skip to content

plugin to add `id` attributes to headings similar to gatsby-remark-autolink-headers

License

Notifications You must be signed in to change notification settings

playfulprogramming/rehype-slug-custom-id

Folders and files

NameName
Last commit message
Last commit date

Latest commit

2bff5c1 Â· Jun 24, 2024

History

83 Commits
Jun 24, 2024
Oct 22, 2016
Mar 10, 2022
Jul 19, 2018
Aug 2, 2021
Jun 24, 2024
Mar 10, 2022
Jun 24, 2024
Jun 24, 2024
Mar 11, 2022
Jun 24, 2024

Repository files navigation

rehype-slug-custom-id

Build Coverage Downloads Size

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.

Related