aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
sync-starlight.mjs anchor mapping drops ###-level headings, producing silent 404 cross-links in mirrors
- Lingua principale
- TypeScript
- Stelle
- 143
- Fork
- 46
- Merge medio
- 3g 9h
- PR unite (30g)
- 20
Descrizione
## 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
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Inizia da sync-starlight.mjs e ispeziona la mappatura di ancore/route utilizzata dai mirror Starlight, quindi esamina i casi correlati di COST_ATTRIBUTION, #repository-onboarding e PR #763. Il lavoro è completato quando il design della mappatura gestisce il caso di livello di intestazione segnalato oppure la sincronizzazione rileva e rifiuta i link riscritti i cui ancoraggi sono assenti dalle pagine generate.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- javascript
- Ambito
- documentation, tooling
- Tipo di issue
- Bug
- Difficoltà
- 4/5
- Tempo stimato
- 3-5 giorni
- Stato di attività
- Tranquilla
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 45/100