Can Eleventy enforce heading hierarchy and required alt text without custom plugins?

Direct Answer

No. Eleventy core does not validate heading hierarchy, does not require alt attributes when using eleventy-img, and incremental builds do not guarantee updated heading structures when only data files change. All three checks require custom transforms or external tooling.

Heading Hierarchy (WCAG 1.3.1)

Eleventy treats templates, layouts, and includes as plain text until they are rendered. There is no build-time pass that parses the combined HTML output and verifies that heading levels (h1–h6) follow a logical outline. A partial included in multiple pages can contain an h2 while the parent page uses an h3, and Eleventy will emit both without warning during eleventy --serve or a production build.

Required Alt Text with eleventy-img

The official @11ty/eleventy-img plugin generates responsive <picture> and <img> markup but does not auto-populate the alt attribute. Authors must supply alt text via front matter, data files, or the plugin’s options object. If the alt property is omitted, the build succeeds and the emitted <img> tag simply lacks an alt attribute (or receives an empty one depending on configuration). No core configuration flag makes alt text mandatory.

Incremental Build Behavior

Eleventy’s watch/incremental mode re-renders a template only when that template’s source file changes. If a heading lives in an included partial or is driven by a data file, editing the partial or the data alone will not trigger re-render of the consuming pages. The output heading structure remains stale until a full eleventy rebuild runs.

How to Add Enforcement Yourself

1. Heading hierarchy: Write an Eleventy transform that loads the rendered HTML with a DOM parser (e.g., JSDOM), walks heading elements, and throws if a level is skipped.
2. Mandatory alt text: Add a transform or a custom shortcode wrapper around eleventy-img that validates the alt option before calling the plugin, throwing on missing or empty values.
3. Full-site verification: Run an external linter (HTMLHint, axe-core, Lighthouse CI) against the generated _site folder as a separate CI step.

Verification Steps

1. Create a layout with an h2 in a partial and a page that uses an h3; run eleventy --serve — no warning appears.
2. Use eleventy-img without providing alt; build succeeds, output lacks alt.
3. Change only a data file that feeds a heading in a partial; run incremental build — output heading does not update until full rebuild.

Assumes Eleventy 2.x/3.x. Behavior may differ in future major versions.

One Diagnostic Detail

Are you using a templating language (Nunjucks, Liquid, 11ty.js) that allows you to write a transform in JavaScript, or do you need a solution that works purely through configuration?