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

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

Aperta
#765 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
bug documentation tooling
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

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.