aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
sync-starlight.mjs anchor mapping drops ###-level headings, producing silent 404 cross-links in mirrors
- 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
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