aws-samples / aws-samples/sample-autonomous-cloud-coding-agents

sync-starlight.mjs anchor mapping drops ###-level headings, producing silent 404 cross-links in mirrors

Abierto
#765 0 comentarios 0 reacciones 0 asignados Ver en GitHub
bug documentation tooling
Lenguaje dominante
TypeScript
Estrellas
143
Forks
46
Merge medio
3 d 10 h
PR fusionados (30 d)
24

Descripción

## Problem

`sync-starlight.mjs` maps only `##`-level `USER_GUIDE.md` anchors when rewriting cross-links for the Starlight mirrors. A `###`-level heading falls through the mapping, and the mirror rewrites the cross-link to a page that does not contain that anchor. The result is a silent 404: the page loads, the anchor jump fails, and `astro check` cannot detect it because the link target page exists.

## Why this is a design issue, not a per-link fix

This is the **third** instance of the anchor/route-mapping bug class in this stack:

1. `COST_ATTRIBUTION` link mapping
2. `#repository-onboarding` anchor
3. The `###` heading caught in self-review on #763 (relinked to `#per-repo-overrides` as a workaround)

Three instances of the same class point at the mapping design rather than the individual links. Candidate directions:

- Map anchors at **all** heading levels, not just `##`
- Add a post-sync link-check step that resolves every rewritten anchor against the generated pages and fails the sync on a miss (closing the gap `astro check` leaves)

## Origin

Found during self-review of PR #763 — see the merge-guidance comment: https://github.com/aws-samples/sample-autonomous-cloud-coding-agents/pull/763#issuecomment-5289889688

Guía de contribución

Abrir la guía de contribución

Línea de trabajo

Comienza con sync-starlight.mjs e inspecciona la asignación de anclas/rutas utilizada por los espejos de Starlight; después, revisa los casos relacionados de COST_ATTRIBUTION, #repository-onboarding y PR #763. Se considera terminado cuando el diseño de la asignación maneja el caso de nivel de encabezado reportado o la sincronización detecta y rechaza los enlaces reescritos cuyos anclajes no están presentes en las páginas generadas.

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

Evaluación

Stack tecnológico
javascript
Área
documentation, tooling
Tipo de issue
Error
Dificultad
4/5
Tiempo estimado
3-5 días
Estado de actividad
Tranquilo
Claridad
Bastante claro
Aptitud para principiantes
45/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.