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

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

Open
#765 0 comments 0 reactions 0 assignees View on GitHub
bug documentation tooling
Dominant language
TypeScript
Stars
143
Forks
46
Avg merge
3d 9h
Merged PRs (30d)
20

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

Contributor guide

Open the contributing guide

Research direction

Start with sync-starlight.mjs and inspect the anchor/route mapping used by the Starlight mirrors, then review the related cases from COST_ATTRIBUTION, #repository-onboarding, and PR #763. Done means the mapping design handles the reported heading-level case or the sync detects and rejects rewritten links whose anchors are absent from generated pages.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation, tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.