remark plugin to add anchors headings using GitHub’s algorithm.
⚠️ Note: This is often useful when compiling to HTML.
If you’re doing that, it’s probably smarter to use
remark-rehype
and rehype-slug
and benefit
from the rehype ecosystem.
Note!
This plugin is ready for the new parser in remark
(remarkjs/remark#536
).
No change is needed: it works exactly the same now as it did previously!
Install
This package is ESM only:
Node 12+ is needed to use it and it must be import
ed instead of require
d.
npm:
npm install remark-slug
Use
Say we have the following file, example.md
:
# Lorem ipsum 😪
## dolor—sit—amet
### consectetur & adipisicing
#### elit
##### elit
And our module, example.js
, looks as follows:
import fs from 'node:fs'
import {unified} from 'unified'
import remarkParse from 'remark-parse'
import remarkSlug from 'remark-slug'
import remarkRehype from 'remark-rehype'
import rehypeStringify from 'rehype-stringify'
const buf = fs.readFileSync('example.md')
unified()
.use(remarkParse)
.use(remarkSlug)
.use(remarkRehype)
.use(rehypeStringify)
.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 & adipisicing</h3>
<h4 id="elit">elit</h4>
<h5 id="elit-1">elit</h5>
API
This package exports no identifiers.
The default export is remarkSlug
.
Add anchors headings using GitHub’s algorithm.
Uses github-slugger
to creates GitHub-style slugs.
Sets data.id
and data.hProperties.id
on headings.
The first can be used by any plugin as a unique identifier, the second tells
mdast-util-to-hast
(used in remark-html
and
remark-rehype
) to use its value as an id
attribute.
Security
Use of remark-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
Contribute
See contributing.md
in remarkjs/.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