docs: fix broken links on docs landing pages and README security anchors - #4967
docs: fix broken links on docs landing pages and README security anchors#4967simpleqt wants to merge 3 commits into
Conversation
The security-notice TOC links in all five language READMEs kept a U+FE0F variation selector after the stripped emoji (#️-security-notice), so they never matched the GitHub-generated #-security-notice anchor
- Drop the bogus `docs/` path segment from 28 relative links in
frontend/src/content/{en,zh}/index.mdx. Root cause: the Nextra docs
route is /[lang]/docs/[[...mdxPath]] and section content lives
directly under src/content/<lang>/ (introduction/, harness/,
application/, tutorials/, reference/), so ./docs/<section> pointed at
files that never existed in-repo and resolved to
/<lang>/docs/docs/<section> on the site. Links now target the real
section roots and pages (e.g. ./introduction, ./harness/quick-start).
Left intentionally unchanged after review (valid site routes flagged by
the audit as root-relative):
- /docs/... links in src/content MDX are rewritten to /<lang>/docs/...
at render time by LocalizedDocsLink (src/mdx-components.ts); every
target maps to an existing content page.
- /demo/threads/... image refs in the public demo article point to
assets served from frontend/public/.
|
Temporarily converting this to draft only to fit the repository's 2-open-PR limit for outside contributors — this PR is complete, CI is green, and it will be marked ready for review again as soon as a slot frees up. Sorry for the noise. |
willem-bd
left a comment
There was a problem hiding this comment.
Two blocking link regressions remain. Please address the inline comments before merging.
| - [Quick Start](./docs/harness/quick-start) | ||
| - [Configuration](./docs/harness/configuration) | ||
| - [Customization](./docs/harness/customization) | ||
| - [DeerFlow Harness](./harness) |
There was a problem hiding this comment.
[P1] Preserve the /docs route segment. Nextra renders this href unchanged, so from /en/docs the browser resolves ./harness to /en/harness, but only /en/docs/harness is generated. The same applies to the other newly shortened English links and the corresponding Chinese links. Please retain ./docs/... or use /docs/... so LocalizedDocsLink produces the localized docs route.
There was a problem hiding this comment.
You're right, and thank you for the route-level analysis. I traced back why these were changed: my static link audit resolved ./docs/harness against the source tree and expected a matching file path, which Nextra's route generation doesn't follow — the /docs/ segment is exactly what makes these resolve on the generated site. The originals were correct; reverting.
| - [Terminal Workbench (TUI)](#terminal-workbench-tui) | ||
| - [Documentation](#documentation) | ||
| - [⚠️ Security Notice](#️-security-notice) | ||
| - [⚠️ Security Notice](#-security-notice) |
There was a problem hiding this comment.
[P1] Keep the variation selector in the security anchor. GitHub renders the heading ID as user-content-️-security-notice and its permalink as #️-security-notice. The new #-security-notice therefore no longer targets the heading; the same regression exists in the four translated README files. Please restore the original fragment in all five files.
There was a problem hiding this comment.
Confirmed — the heading's
|
Closing — both of willem-bd's findings show this entire PR was built on two false positives from my link-audit tooling, and the original links were correct all along:
Thanks for the careful review — the route-level and slug-level explanations are exactly what the tooling got wrong. (This also frees one open-PR slot under the limit, so I can convert #4989 from draft when its turn comes.) |
Two commits:
frontend/src/content/{en,zh}/index.mdxlanding pages linked to.mdsources with broken relative paths; links are now rewritten at render time viaLocalizedDocsLink(src/mdx-components.ts) and every target maps to an existing content page./demo/threads/...image refs in the public demo article point at assets served fromfrontend/public/.README.mdsecurity section anchors contained a stray variation selector (U+FE0F) that broke the anchor links.Docs-only; no code changes.