Manual ARIA injection vs. waiting for native navigation plugin support in Eleventy

Direct answer

For a site that will grow to dozens of distinct navigation regions (header, sidebar, footer, breadcrumb, etc.), a parameterized shortcode or filter that wraps the plugin's output in a <nav aria-label="…"> scales better than relying on the data cascade or eleventyComputed. The wrapper keeps accessibility markup visible in templates, allows each region to set its own label, and can be centralized in one helper file. Waiting for native ARIA support is not recommended because the plugin's roadmap has not committed to it, and any future native implementation would require migration anyway.

Open questions answered

1. Which approach scales better?

A reusable wrapper (Approach A) scales better. Each navigation region calls the same shortcode with a distinct aria-label and optional landmark attributes. This avoids duplicating wrapper logic across layouts while keeping the decision explicit in the template. Central injection via the data cascade (Approach B) reduces repetition but hides accessibility markup from template review and makes special-case labels (e.g., a footer nav needing a different label) harder to override.

2. Is there a documented pattern for extending the plugin's output without forking?

Eleventy does not provide an official extension point for the navigation plugin's HTML output. The common pattern is to create a shortcode or filter that receives the plugin's rendered list and returns a wrapped version. This keeps the plugin intact and avoids forking.

3. What are the risks of a custom wrapper if native ARIA support arrives later?

The main risk is double-wrapping (e.g., two <nav> elements or duplicate role="navigation"). Mitigate this by making the wrapper conditional: only inject ARIA attributes when they are not already present. Centralize the wrapper so a single change can disable it if native support lands.

Confirmed fact vs. likely explanation

• Confirmed: The navigation plugin emits plain <ul>/<li> markup without ARIA landmarks or author-controlled labels.
• Likely: A parameterized shortcode gives immediate WCAG 2.1 AA control and keeps accessibility decisions visible in templates.
• Likely: Central injection via eleventyComputed moves presentation markup into data logic, complicating per-region overrides.
• Likely: For many regions, a single parameterized helper scales better than global data-cascade injection.
• Likely: Migration risk is lower if the wrapper is centralized, documented, and designed to detect existing ARIA landmarks.

Verification steps (run in your project)

1. Render a page that uses the navigation plugin and inspect the HTML. Confirm whether <nav>, role="navigation", or aria-label are already present.
2. Create a shortcode navWrapper that accepts the navigation HTML, an ariaLabel, and optional role. Return <nav aria-label="{{ ariaLabel }}">{{ content }}</nav>.
3. Use the shortcode in header, sidebar, footer, and breadcrumb templates, passing distinct labels. Verify each region has a unique accessible name.
4. Run an accessibility checker (e.g., axe-core) or browser inspector to confirm no duplicated landmarks.
5. Simulate future native support: modify the shortcode to skip wrapping when role="navigation" exists on the root element. Confirm output is not double-wrapped.

One missing diagnostic detail

What version of Eleventy and the @11ty/eleventy-navigation plugin are you using? This determines whether any native ARIA support is already available and changes the urgency of a custom wrapper.