website: make content headings keyboard-focusable so Tab moves through the page

Aperta Adatta ai principianti
  • Qualcosa non va?
#26,581 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@nightcityblade ci sta già lavorando.

Dal 8/10/2026.

  • #26588 di @nightcityblade — aperta
  • #26639 di @fatmagnd — aperta

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
78/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
html
Ambito
accessibility

Direzione di ricerca

Leggi website/layouts/_default/_markup/render-heading.html e confrontane l’output con website/layouts/partials/heading.html, che rende già focalizzabili alcuni titoli. Verifica la documentazione renderizzata del sito web e il comportamento della tastiera in modalità chiara e scura. Il lavoro è completato quando è possibile raggiungere i titoli del contenuto Markdown con Tab e il loro focus è visibile; il comportamento non correlato della barra di navigazione è fuori ambito.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

domain:website good first issue
A note for the community
  • Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request
  • If you are interested in working on this issue or have submitted a pull request, please leave a comment
Use Cases

Keyboard users read a docs page with the Tab key. Each Tab moves focus to the next focusable element, and the browser scrolls the page to that element.

On vector.dev, headings in the page content are not focus stops. Only links, buttons, and code blocks get focus. On a page with long sections and few links, one Tab can jump past one or more full sections. The user cannot move through the document section by section.

Example on https://vector.dev/docs/setup/quickstart/: after the breadcrumbs, the Tab sequence in the content is:

button "Script"
button "Docker"
pre    "curl --proto '=https' ..."
a      "installation methods"
pre    "vector --version"
a      "configuration file"
...

No heading in the page gets focus.

The Datadog docs do this correctly. On https://docs.datadoghq.com/getting_started/, each heading is a focus stop, for example:

<h2 id="what-is-datadog"><a href="#what-is-datadog">What is Datadog?</a></h2>

Tab moves from the breadcrumbs to "What is Datadog?", then to the links in that section, then to the next heading.

Attempted Solutions

NA

Current behavior in the website source:

  • website/layouts/_default/_markup/render-heading.html renders all Markdown headings. The heading text is plain text. The only link is the # icon, and it has x-show="show". That icon shows only on mouseover, so it has display: none for keyboard users and is not focusable.
  • website/layouts/partials/heading.html wraps the heading text in <a href="#id"> when anchor is true (for example, the component reference pages in website/layouts/partials/data.html). These headings are already focus stops. Thus, the site is not consistent: Markdown headings are not focusable, and some template headings are.
Proposal

Keyboard users must be able to move through a docs page section by section with the Tab key, the same as on the Datadog docs. The focused element must be visible in light mode and dark mode.

One possible fix is to wrap the heading text in render-heading.html in an <a href="#..."> link, similar to heading.html with anchor: true and the Datadog docs. We did not test this, and other approaches are welcome.

Related: the first Tab on every page focuses the full <nav> element (tabindex="0" in website/layouts/partials/navbar.html), and the navbar itself is not interactive.

A larger follow-up can compare other keyboard features with the Datadog docs (for example, a "skip to content" link), but that is not necessary for this issue.

References
  • #26572: adds copy buttons to code blocks. During review, we found this problem. Out of scope for that PR.
Version

NA (website)

Lingua principale
Rust
Stelle
22.8k
Fork
2.4k
Merge medio
1g 13h
PR unite (30g)
273

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di vectordotdev/vector

Tutte le issue di vectordotdev/vector

Issue simili

Altre issue su Rust

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.