Adding Custom Anchors to Headings in Markdown – Eleventy

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 …

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-anchors and markdown-it-attrs.

The markdown-it-anchors 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-anchors 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.

This post was originally published in Syntackle


Print Share Comment Cite Upload Translate
APA
Murtuzaali Surti | Sciencx (2024-03-29T11:03:32+00:00) » Adding Custom Anchors to Headings in Markdown – Eleventy. Retrieved from https://www.scien.cx/2022/07/11/adding-custom-anchors-to-headings-in-markdown-eleventy/.
MLA
" » Adding Custom Anchors to Headings in Markdown – Eleventy." Murtuzaali Surti | Sciencx - Monday July 11, 2022, https://www.scien.cx/2022/07/11/adding-custom-anchors-to-headings-in-markdown-eleventy/
HARVARD
Murtuzaali Surti | Sciencx Monday July 11, 2022 » Adding Custom Anchors to Headings in Markdown – Eleventy., viewed 2024-03-29T11:03:32+00:00,<https://www.scien.cx/2022/07/11/adding-custom-anchors-to-headings-in-markdown-eleventy/>
VANCOUVER
Murtuzaali Surti | Sciencx - » Adding Custom Anchors to Headings in Markdown – Eleventy. [Internet]. [Accessed 2024-03-29T11:03:32+00:00]. Available from: https://www.scien.cx/2022/07/11/adding-custom-anchors-to-headings-in-markdown-eleventy/
CHICAGO
" » Adding Custom Anchors to Headings in Markdown – Eleventy." Murtuzaali Surti | Sciencx - Accessed 2024-03-29T11:03:32+00:00. https://www.scien.cx/2022/07/11/adding-custom-anchors-to-headings-in-markdown-eleventy/
IEEE
" » Adding Custom Anchors to Headings in Markdown – Eleventy." Murtuzaali Surti | Sciencx [Online]. Available: https://www.scien.cx/2022/07/11/adding-custom-anchors-to-headings-in-markdown-eleventy/. [Accessed: 2024-03-29T11:03:32+00:00]
rf:citation
» Adding Custom Anchors to Headings in Markdown – Eleventy | Murtuzaali Surti | Sciencx | https://www.scien.cx/2022/07/11/adding-custom-anchors-to-headings-in-markdown-eleventy/ | 2024-03-29T11:03:32+00:00
https://github.com/addpipe/simple-recorderjs-demo