- Stable
3.0.0- Canary
3.0.1-alpha.1
Toggle Menu
Eleventy
5.81sGatsby
43.36sId 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
idattributes on your page will not be modified. - If two headings on the page have the same text, we’ll de-duplicate the
idattributes we assign automatically. - If a heading’s text would result in a conflict with any existing
idattribute on the page, we’ll de-duplicate the newidautomatically.
This is best paired with a user interface piece to add anchor links to heading elements in an accessible way. A few options:
<heading-anchors>from David Darnes<heading-anchors>from Zach Leatherman (only for anchor links as siblings)
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 &) to their counterparts before slugify-ing
decodeEntities: true,
// check for duplicate `id` attributes in application code?
checkDuplicates: "error", // `false` to disable
// 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 &) to their counterparts before slugify-ing
decodeEntities: true,
// check for duplicate `id` attributes in application code?
checkDuplicates: "error", // `false` to disable
// 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;
}
});
}