Adding Custom Anchors to Headings in Markdown - Eleventy

Murtuzaali Surti
Murtuzaali Surti

• 2 min read

Updated On

Anchors are nothing but id attributes applied to an element to link to it using href attribute internally on the same page.

By default, 11ty uses markdown-it library to parse markdown. But, it seems that by default, markdown-it doesn't support syntax for applying an id to a header element.

The syntax for applying a custom id to a header element in markdown is as follows:

## text {#id}

To make that syntax work, you need to create your own instance of markdown-it library and add two plugins, markdown-it-anchor and markdown-it-attrs.

The markdown-it-anchor plugin will apply a default id depending on the heading text automatically to every header element in our markup.

The markdown-it-attrs plugin will replace the default id with the custom id you specify.

Applying Custom Anchors #

Install the required dependencies:

npm i markdown-it markdown-it-anchor markdown-it-attrs

Require them inside .eleventy.js file,

const markdownIt = require('markdown-it');
const markdownItAnchor = require('markdown-it-anchor');
const markdownItAttrs = require('markdown-it-attrs');

Create an instance of the markdown-it library inside the module.exports function.

eleventyConfig.setLibrary("md", markdownIt().use(markdownItAnchor).use(markdownItAttrs))

You can also add some options such as:

let markdownItOptions = {
    html: true // you can include HTML tags

let markdownItAnchorOptions = {
    level: 2 // minimum level header -- anchors will only be applied to h2 level headers and below but not h1

eleventyConfig.setLibrary("md", markdownIt(markdownItOptions).use(markdownItAnchor, markdownItAnchorOptions).use(markdownItAttrs))

Now, if you do something like:

## Heading 1 {#head1}

In this case, head1 will be the id of this header element. You can link to this element by using #head1 as the href value. That's how you can add custom anchors to heading elements.

Applying Default Anchors #

If you don't want a custom id and just want to keep the default id that's being applied to the element by the markdown-it-anchor plugin, then remove the markdown-it-attrs plugin and you will get a default anchor applied to the element.

eleventyConfig.setLibrary("md", markdownIt(markdownItOptions).use(markdownItAnchor, markdownItAnchorOptions))

That's all for now. Signing Off.

How to vendor prefix and minify CSS?


Deploying React App to Netlify