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

Abierto Apto para principiantes
  • ¿Algo no está bien?
#26,581 2 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

@nightcityblade ya está trabajando en esto.

Desde el 8/10/2026.

  • #26588 de @nightcityblade — abierto
  • #26639 de @fatmagnd — abierto

Evaluación

Dificultad
2/5
Tiempo estimado
1-3 horas
Aptitud para principiantes
78/100
Tipo de issue
Nueva funcionalidad
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
html
Área
accessibility

Línea de trabajo

Lee website/layouts/_default/_markup/render-heading.html y compara su salida con website/layouts/partials/heading.html, que ya hace que algunos encabezados se puedan enfocar. Comprueba la documentación renderizada del sitio web y el comportamiento del teclado en los modos claro y oscuro. Se considera terminado cuando se puede llegar a los encabezados del contenido Markdown con Tab y su foco es visible; el comportamiento no relacionado de la barra de navegación queda fuera del alcance.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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)

Lenguaje dominante
Rust
Estrellas
22.8k
Forks
2.4k
Merge medio
1 d 13 h
PR fusionados (30 d)
273

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de vectordotdev/vector

Todos los issues de vectordotdev/vector

Issues similares

Más issues de Rust

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.