rehype-slug

What is rehype-slug?

The rehype-slug npm package is a plugin for the rehype ecosystem, which is used to process HTML with plugins. This particular plugin automatically adds slugs (URL-friendly identifiers) to headings in HTML documents. These slugs can be used to create anchor links for easy navigation within the document, enhancing the usability and accessibility of web pages.

What are rehype-slug's main functionalities?

Automatic Slug Generation for Headings

This feature automatically generates slugs for each heading in an HTML document. The code sample shows how to use rehype with the rehype-slug plugin to process an HTML string containing a heading, adding an id attribute to the heading based on its content.

const rehype = require('rehype');
const rehypeSlug = require('rehype-slug');

rehype()
  .use(rehypeSlug)
  .process('<h1>Your Heading Here</h1>', function(err, file) {
    console.log(String(file));
  });

Other packages similar to rehype-slug

remark-slug

Similar to rehype-slug, remark-slug is a plugin but for the remark ecosystem, which is used for processing Markdown. It also generates slugs for headings in Markdown documents. While rehype-slug works on HTML, remark-slug is specifically tailored for Markdown, making it suitable for different types of content sources.

gatsby-remark-autolink-headers

This Gatsby plugin automatically adds anchor links to headers in Markdown files processed through Gatsby's remark transformer. It is similar to rehype-slug in functionality but is specifically designed to integrate with the Gatsby static site generator, providing a more seamless experience for Gatsby users compared to using a general-purpose plugin like rehype-slug.

README

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:

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.

Related

• 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

MIT © Titus Wormer