remark-slug

Add anchors to remark heading nodes using GitHub’s algorithm.

:warning: 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.

Installation

npm:

1npm install remark-slug

Usage

Say we have the following file, example.md:

1# Lorem ipsum 😪
2
3## dolor—sit—amet
4
5### consectetur & adipisicing
6
7#### elit
8
9##### elit

And our script, example.js, looks as follows:

1var fs = require('fs');
2var unified = require('unified');
3var markdown = require('remark-parse');
4var slug = require('remark-slug');
5var remark2rehype = require('remark-rehype');
6var html = require('rehype-stringify');
7
8unified()
9  .use(markdown)
10  .use(slug)
11  .use(remark2rehype)
12  .use(html)
13  .process(fs.readFileSync('example.md'), function (err, file) {
14    if (err) throw err;
15    console.log(String(file));
16  });

Now, running node example yields:

1<h1 id="lorem-ipsum-">Lorem ipsum 😪</h1>
2<h2 id="dolorsitamet">dolor—sit—amet</h2>
3<h3 id="consectetur--adipisicing">consectetur &#x26; adipisicing</h3>
4<h4 id="elit">elit</h4>
5<h5 id="elit-1">elit</h5>

API

remark.use(slug)

Adds slugs to markdown headings.

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

Sets data.id, data.hProperties.id on heading nodes. The first can be used by any plugin as a unique identifier, the second tells remark-html to use its value as an id attribute. remark-slug does not overwrite these values when they already exist.

Related

• rehype-slug — Add slugs to headings in HTML

License

MIT © Titus Wormer