Skip to navigation Skip to main content
Eleventy
Eleventy Documentation
Stable
3.0.0
Toggle Menu
Eleventy 1.93s
Next.js 70.65s

Id Attribute Added in v3.0.0

Contents

The Id Attribute plugin adds id attributes to headings on your page (<h1> through <h6>). This was added to allow deep linking to different sections of blog posts and is compatible with all template languages in Eleventy that output HTML. Related GitHub #3363.

  • Existing id attributes on your page will not be modified.
  • If two headings on the page have the same text, we’ll de-duplicate the id attributes we assign automatically.
  • If a heading’s text would result in a conflict with any existing id attribute on the page, we’ll de-duplicate the new id automatically.

This is best paired with a user interface piece to add anchor links to heading elements in an accessible way. A few options:

Examples

<h1>Welcome to Eleventy</h1>

is transformed into:

<h1 id="welcome-to-eleventy">Welcome to Eleventy</h1>

Ignore a node Added in v3.0.0

Use the eleventy:id-ignore attribute on a child node to ignore it (only for the purposes of id attribute generation).

<h1>Welcome to Eleventy<span eleventy:id-ignore> ignore this</span></h1>

is transformed into:

<h1 id="welcome-to-eleventy">Welcome to Eleventy</h1>

Usage

This plugin is bundled with Eleventy and requires no additional package installation (though you do need to opt-in via addPlugin).

eleventy.config.js
import { IdAttributePlugin } from "@11ty/eleventy";

export default function (eleventyConfig) {
eleventyConfig.addPlugin(IdAttributePlugin);
}
module.exports = async function (eleventyConfig) {
const { IdAttributePlugin } = await import("@11ty/eleventy");

eleventyConfig.addPlugin(IdAttributePlugin);
}

With options

eleventy.config.js
import { IdAttributePlugin } from "@11ty/eleventy";

export default function (eleventyConfig) {
eleventyConfig.addPlugin(IdAttributePlugin, {
selector: "h1,h2,h3,h4,h5,h6", // default

// swaps html entities (like &amp;) to their counterparts before slugify-ing
decodeEntities: true,

// by default we use Eleventy’s built-in `slugify` filter:
slugify: eleventyConfig.getFilter("slugify"),

filter: function({ page }) {
if(page.inputPath.endsWith("test-skipped.html")) {
return false; // skip
}

return true;
}
});
}
module.exports = async function (eleventyConfig) {
const { IdAttributePlugin } = await import("@11ty/eleventy");

eleventyConfig.addPlugin(IdAttributePlugin, {
selector: "h1,h2,h3,h4,h5,h6", // default

// swaps html entities (like &amp;) to their counterparts before slugify-ing
decodeEntities: true,

// by default we use Eleventy’s built-in `slugify` filter:
slugify: eleventyConfig.getFilter("slugify"),

filter: function({ page }) {
if(page.inputPath.endsWith("test-skipped.html")) {
return false; // skip
}

return true;
}
});
}

Other pages in Official Plugins: