docs: address fragment review feedback

2026-08-13 14:30:17 +08:00
parent 4201bbceca
commit 3a1a4e2cd8
7 changed files with 51 additions and 15 deletions
@@ -49,7 +49,7 @@ Write normal repository-relative Markdown links in canonical docs. The projector
 - An image is the exception: its file is copied into the generated tree and referenced from there, so the site serves it regardless of repository visibility. It must be a regular file inside the repository.
 - External URLs, site-absolute URLs, email links, and fragment-only links remain unchanged.
 - A missing repository-relative target fails projection instead of silently producing a broken link.
- Cross-language and generated-document fragments use the English GitHub heading id as their canonical id. If a translated or generated heading emits another id, place an explicit `<a id="..."></a>` immediately before it; add generated aliases in the owning generator.
+- Cross-page fragments use the English GitHub heading id as their canonical id. If an authored heading emits a different VitePress id, place an explicit `<a id="..."></a>` immediately before it; add generated aliases in the owning generator.

 Do not write website-specific routes into canonical Markdown just to satisfy VitePress. Use `sourceAliases` for directory-style repository links that should resolve to a mapped index page.

@@ -69,6 +69,8 @@ Run the focused website gate before treating the mapping as valid:
 pnpm docs:check
 ```

+If Markdown link checks pass but the site build reports a missing fragment, follow the `verify-doc-site-fragments` source and target paths. Preserve the English GitHub id with an explicit alias in authored Markdown or in the owning generator.
+
 Before committing a documentation-site change, run:

 ```sh