aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
sync-starlight.mjs anchor mapping drops ###-level headings, producing silent 404 cross-links in mirrors
- Ngôn ngữ chính
- TypeScript
- Star
- 143
- Fork
- 46
- Merge trung bình
- 3 ngày 10 giờ
- Pull request đã merge (30 ngày)
- 24
Mô tả
## 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
Hướng dẫn đóng góp
Hướng nghiên cứu
Bắt đầu với sync-starlight.mjs và kiểm tra ánh xạ anchor/route được các bản mirror Starlight sử dụng, sau đó xem xét các trường hợp liên quan từ COST_ATTRIBUTION, #repository-onboarding và PR #763. Được xem là hoàn tất khi thiết kế ánh xạ xử lý trường hợp cấp heading đã được báo cáo hoặc quá trình sync phát hiện và từ chối các liên kết đã được viết lại có anchor không tồn tại trong các trang được tạo.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- javascript
- Lĩnh vực
- documentation, tooling
- Loại issue
- Lỗi
- Độ khó
- 4/5
- Thời gian dự kiến
- 3-5 ngày
- Mức độ hoạt động
- Ít trao đổi
- Độ rõ ràng
- Khá rõ ràng
- Mức phù hợp với người mới
- 45/100