remark-slug

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 imported instead of required.

npm:

npm install remark-slug

Use

Say we have the following file, example.md:

# Lorem ipsum ????

## dolor—sit—amet

### consectetur &amp; 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 &#x26; adipisicing</h3>
<h4 id="elit">elit</h4>
<h5 id="elit-1">elit</h5>

API

This package exports no identifiers. The default export is remarkSlug.

`unified().use(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.

rehype-slug — Add slugs to headings in HTML

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

Current Tags

7.0.1 ... latest (4 years ago)

6 Versions

4.2.3 ... 8 years ago
7.0.1 ... 4 years ago
7.0.0 ... 4 years ago
6.1.0 ... 4 years ago
6.0.0 ... 5 years ago
5.1.2 ... 6 years ago