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

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

Offen
#765 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
bug documentation tooling
Vorherrschende Sprache
TypeScript
Sterne
143
Forks
46
Ø Merge
3 T. 9 Std.
Gemergte PRs (30 T.)
20

Beschreibung

## 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

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Beginne mit sync-starlight.mjs und untersuche die Anker-/Routen-Zuordnung, die von den Starlight-Spiegeln verwendet wird, und prüfe dann die verwandten Fälle aus COST_ATTRIBUTION, #repository-onboarding und PR #763. Als erledigt gilt die Aufgabe, wenn das Zuordnungsdesign den gemeldeten Fall auf Überschriftenebene behandelt oder der Sync umgeschriebene Links erkennt und ablehnt, deren Anker in den generierten Seiten fehlen.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
javascript
Bereich
documentation, tooling
Issue-Typ
Bug
Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Aktivitätsstatus
Ruhig
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
45/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.