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

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

Ouverte
#765 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub
bug documentation tooling
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

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.