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

Add ids to headings with rehype.

Installation

npm:

npm install rehype-slug

Usage

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:

var fs = require('fs')
var rehype = require('rehype')
var slug = require('rehype-slug')

rehype()
  .data('settings', {fragment: true})
  .use(slug)
  .process(fs.readFileSync('fragment.html'), function(err, file) {
    if (err) throw err
    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

rehype().use(slug)

Adds id properties to h1-h6 headings which don’t already have one.

Uses github-slugger (thus creating GitHub style ids).

Related

• remark-slug — Add slugs to headings in markdown

Contribute

See contributing.md in rehypejs/rehype for ways to get started.

This organisation has a Code of Conduct. By interacting with this repository, organisation, or community you agree to abide by its terms.

License

MIT © Titus Wormer