rehype-slugify
rehype plugin to add ids to headings using a slugger of your choice
Contents
What's this?
This package is a unified (rehype) plugin to add ids to headings. It looks for headings (<h1> through <h6>) that do not yet have ids and adds id attributes to them based on the text they contain. You'll have to provide an implementation of the algorithm that does that, such as github-slugger, @sindresorhus/slugify,etc.
When should I use this?
This plugin is useful when you have relatively long documents and you want to be able to link to particular sections.
A different plugin, rehype-autolink-headings, adds links to these headings back to themselves, which is useful as it lets users more easily link to particular sections.
This plugin allows you to use your own slug algorithm to handle usecases that rehype-slug does not allow (e.g, additional language support, custom replacements, etc)
Install
This package is ESM only.
In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:
npm install @microflash/rehype-slugify
In Deno, with esm.sh:
import rehypeSlugify from 'https://esm.sh/@microflash/rehype-slugify'
In browsers, with esm.sh:
<script type="module">
import rehypeSlugify from 'https://esm.sh/@microflash/rehype-slugify?bundle'
</script>
Use
Say we have the following file example.html:
<h1 id=some-id>Lorem ipsum</h1>
<h2>Dolor sit amet 😪</h2>
<h3>consectetur & adipisicing</h3>
<h4>elit</h4>
<h5>elit</h5>
And our module example.js looks as follows:
import Slugger from 'github-slugger'
import { read } from 'to-vfile'
import { rehype } from 'rehype'
import rehypeSlugify from '@microflash/rehype-slugify'
const slugger = new Slugger()
main()
async function main() {
const file = await rehype()
.data('settings', { fragment: true })
.use(rehypeSlugify, {
reset() {
slugger.reset()
},
slugify(text) {
return slugger.slug(text)
}
})
.process(await read('example.html'))
console.log(String(file))
}
Running that with node example.js yields:
<h1 id="some-id">Lorem ipsum</h1>
<h2 id="dolor-sit-amet-">Dolor sit amet 😪</h2>
<h3 id="consectetur--adipisicing">consectetur & adipisicing</h3>
<h4 id="elit">elit</h4>
<h5 id="elit-1">elit</h5>
API
The default export is rehypeSlugify.
Options
The following options are available. All of them are required.
reset: function that resets the slug counterslugify: function that slugifies the text
Security
Use of @microflash/rehype-slugify can open you up to a cross-site scripting (XSS) attack as it sets id attributes on headings, which causes what is known as "DOM clobbering". Please use rehype-sanitize and see its Example: headings (DOM clobbering) for information on how to properly solve it.
Related
License
MIT
