fix(theme): improve docs sidebar accessibility

[yoshibase]

Summary

Fixes #8429 (landmark structure only)

The docs sidebar currently nests landmarks: an outer <aside> (complementary) wraps an inner <nav aria-label="Docs sidebar">. NVDA announces both before you reach any doc link — "complementary landmark … docs sidebar navigation landmark …".

This PR:

• Replaces the outer <aside> with a plain <div> container (no complementary landmark)
• Moves the single <nav aria-label="Docs sidebar"> to wrap the logo, menu, and collapse button together

Issue #8429 also mentions hiding the duplicate sidebar logo from screen readers when navbar.hideOnScroll is on. I left that out of this PR on purpose — I will open a separate follow-up for it so reviewers can evaluate one concern at a time.

Test plan

Preview: https://deploy-preview-12283--docusaurus-2.netlify.app/docs/introduction

Compare against main: https://docusaurus.io/docs/introduction

Tools: Chrome, NVDA (Windows) or VoiceOver (macOS), DevTools

1. Inspect the DOM (Chrome DevTools)

1. Open the deploy preview docs page.
2. Right-click the left doc sidebar → Inspect.
3. Walk up the tree from a sidebar menu link.

Expected after this PR:

<div class="...docSidebarContainer...">
  <div class="...sidebarViewport...">
    <nav aria-label="Docs sidebar" class="...sidebar...">
      <!-- logo (if hideOnScroll), menu <ul>, collapse button -->
    </nav>
  </div>
</div>

On main today:

<aside class="...docSidebarContainer...">
  ...
    <div class="...sidebar...">
      <nav aria-label="Docs sidebar"> ... </nav>
    </div>
  ...
</aside>

The point: one navigation landmark for the sidebar, not complementary + navigation.

2. NVDA landmark list

1. Install NVDA: https://www.nvaccess.org/download/
2. Open the preview URL in Chrome with NVDA running.
3. Press NVDA + F7 → Landmarks tab.

Check	Main (docusaurus.io)	This PR preview
Complementary landmark for docs sidebar	Yes (<aside>)	No
Navigation landmark "Docs sidebar"	Yes (nested inside complementary)	Yes (standalone)

3. Keyboard navigation still works

1. Press Tab repeatedly through the sidebar links.
2. All doc links should be reachable in the same order as before.
3. If your site config has a collapsible sidebar, the collapse button should still work.

4. VoiceOver spot check (macOS)

1. Safari → preview URL.
2. VO + U → Landmarks rotor.
3. Confirm there is a Docs sidebar navigation landmark and no extra complementary landmark for the sidebar column.

5. axe DevTools (optional)

Scan the page with axe DevTools. Removing a redundant <aside> should not introduce new violations. Landmark-related informational notices are fine — compare against main rather than expecting zero notices.

What proves the fix

Steps 1–2 show the sidebar is exposed as one navigation landmark instead of complementary + navigation stacked together. That matches the structure requested in #8429.

[meta-cla]

Hi @yoshibase!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at cla@meta.com. Thanks!

[netlify]

✅ [V2]

Built without sensitive environment variables

Name	Link
🔨 Latest commit	fa1919d
🔍 Latest deploy log	https://app.netlify.com/projects/docusaurus-2/deploys/6a5527cc5cb86d00080e32a5
😎 Deploy Preview	https://deploy-preview-12283--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[meta-cla]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

[slorber]

Please fix one thing at a time, not 3.

And respect our issue template: you must tell us exactly how to test your changes

Note: We do not accept vibe-coded PRs that you throw at Cursor and do not even understand. Please show that you actually put human work behind this PR, by showing you clear understanding of each things you try to fix.

[yoshibase]

Thanks for the feedback.

Two changes:

1. Scope — I removed the hideOnScroll logo aria-hidden logic from this PR. It now only does the landmark restructuring (<aside> → <div>, single <nav aria-label="Docs sidebar">). I'll open a separate PR for the duplicate-logo screen reader issue.

2. Test plan — The PR description now walks through DevTools DOM inspection, NVDA landmark list (NVDA+F7), keyboard navigation, and an optional VoiceOver/axe check. Deploy preview link included.

[yoshibase]

Closing this PR — branch history rewrite left the PR head stuck on the old commit.

Reopened the work as #12291 with:

• landmark-only scope (logo aria-hidden deferred)
• expanded test plan in the PR description
• clean commit history