aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
sync-starlight.mjs anchor mapping drops ###-level headings, producing silent 404 cross-links in mirrors
- Langage dominant
- TypeScript
- Étoiles
- 143
- Forks
- 46
- Merge moyen
- 3 j 10 h
- PR mergées (30 j)
- 24
Description
## 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
Guide de contribution
Ouvrir le guide de contribution
Piste de recherche
Commencez par sync-starlight.mjs et examinez le mappage des ancres/routes utilisé par les miroirs Starlight, puis examinez les cas associés de COST_ATTRIBUTION, #repository-onboarding et PR #763. La tâche est terminée lorsque la conception du mappage gère le cas de niveau de titre signalé ou que la synchronisation détecte et rejette les liens réécrits dont les ancres sont absentes des pages générées.
Rédigé par le modèle d'indexation à partir du texte de l'issue.
Évaluation
- Stack technique
- javascript
- Domaine
- documentation, tooling
- Type d'issue
- Bug
- Difficulté
- 4/5
- Temps estimé
- 3-5 jours
- Activité
- Calme
- Clarté
- Plutôt claire
- Accessibilité débutants
- 45/100