Scaladoc ARIA landmarks missing in generated HTML documentation

Direct answer

The landmark mapping itself is the easy part; the tooling questions are where the uncertainty lives, because Scaladoc currently has no built-in flag or sbt setting for ARIA landmark injection (as of October 2026, to my knowledge). So this is a design proposal, not a configuration you can switch on today.

1. Which elements should get which roles

This part is well-established accessibility practice and independent of Scaladoc internals:

• role="navigation" on the <nav> element (or the header/sidebar container holding the package and type lists). Note that a native <nav> element already exposes the navigation landmark implicitly in modern browsers, so the explicit role is mainly a fallback for older assistive technology.
• role="main" on the <main> element wrapping the primary API content (the class/trait/object documentation). Again, <main> is implicitly a main landmark; the explicit role is redundant but harmless.
• role="complementary" on any <aside> sidebar with related links, inheritance hierarchies, or metadata.

The more robust fix is often to use the semantic HTML5 elements (<nav>, <main>, <aside>) rather than bolt roles onto generic <div>s — that gives you landmarks without any ARIA at all.

2. Default behavior vs. opt-in flag

Likely recommendation, not confirmed consensus: making landmarks the default is defensible precisely because semantic elements and non-duplicate landmark roles are backward-compatible — they don't change rendering and only add information for assistive tech. An opt-in flag means almost nobody benefits. However, I cannot verify current community preference on this, and a flag is the safer first step if maintainers worry about themes that style <div> structure and would break when elements change to <nav>/<main>. If a flag is added, it would be a new Scaladoc option and a corresponding sbt Compile / doc / scalacOptions entry — the exact names would be decided in the PR, so don't search for an existing setting.

3. Avoiding conflicts with plugins and backends

The key rules that hold regardless of implementation:

• Never emit a duplicate landmark. Two role="main" regions on one page break screen-reader landmark navigation. If a plugin (sbt-site, mdoc, or a custom theme) already wraps Scaladoc output in its own <main>, Scaladoc's inner content should not add another.
• Only add a role when the element lacks one. Conditional insertion preserves plugin-provided roles.
• Treat Scala 2.13 and Scala 3 separately. This is the biggest caveat: Scala 3's Scaladoc is a distinct static-site generator (based on the Dokka-derived architecture, with its own templates and an sbt-site-style static site layout), while Scala 2.13 Scaladoc uses its own older template set. There is no single template.html edit that covers both — each backend needs its own change, and the file names/locations differ by version. Verify against the actual sources for your target version before proposing a patch.
• Plugins that inject markup via JavaScript after page load can create landmarks the static HTML can't see; coordination (or a documented disable option) is needed there.

Verification once implemented

1. Generate docs and inspect the HTML: exactly one main landmark, one navigation landmark, complementary landmarks only on sidebars.
2. Run an automated audit (axe-core or pa11y) and confirm no "duplicate landmark" or "landmark not contained" violations.
3. Test with a screen reader (NVDA's landmark list, or VoiceOver's rotor) to confirm the regions appear and are jumpable.
4. Generate with a plugin-heavy setup (sbt-site/mdoc) to confirm no conflicts.

Uncertainty note: the element-to-role mapping and duplicate-landmark rules are solid; everything about specific Scaladoc flags, template file names, and per-version architecture should be checked against the current Scala 2.13/3.x sources before writing the patch.