Skip to content

docs: fix broken links on docs landing pages and README security anchors - #4967

Closed
simpleqt wants to merge 3 commits into
bytedance:mainfrom
simpleqt:fix-docs-landing-links
Closed

docs: fix broken links on docs landing pages and README security anchors#4967
simpleqt wants to merge 3 commits into
bytedance:mainfrom
simpleqt:fix-docs-landing-links

Conversation

@simpleqt

Copy link
Copy Markdown
Contributor

Two commits:

  1. frontend/src/content/{en,zh}/index.mdx landing pages linked to .md sources with broken relative paths; links are now rewritten at render time via LocalizedDocsLink (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 from frontend/public/.
  2. README.md security section anchors contained a stray variation selector (U+FE0F) that broke the anchor links.

Docs-only; no code changes.

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/.
Copilot AI lite review requested due to automatic review settings August 23, 2026 12:56

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@CLAassistant

CLAassistant commented Aug 23, 2026

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@github-actions github-actions Bot added area:docs Documentation and Markdown only area:frontend Next.js frontend under frontend/ risk:low Low risk: docs / i18n / assets only size/S PR changes 20-100 lines labels Aug 23, 2026
@simpleqt
simpleqt marked this pull request as draft August 24, 2026 03:56
@simpleqt

Copy link
Copy Markdown
Contributor Author

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.

@WillemJiang
WillemJiang marked this pull request as ready for review August 25, 2026 02:01

@willem-bd willem-bd left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread README.md
- [Terminal Workbench (TUI)](#terminal-workbench-tui)
- [Documentation](#documentation)
- [⚠️ Security Notice](#-security-notice)
- [⚠️ Security Notice](#-security-notice)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed — the heading's ⚠️ carries U+FE0F and GitHub preserves it in the slug, so my tool's normalization that stripped the variation selector was wrong here. The original fragment was correct in all five files; reverting.

@simpleqt

Copy link
Copy Markdown
Contributor Author

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:

  1. The ./docs/... prefixes on the landing pages are required by Nextra's route generation; shortening them broke resolution to /en/harness-style paths that don't exist.
  2. GitHub preserves the U+FE0F variation selector in the ⚠️ heading slug, so #️-security-notice was already the right fragment; stripping it broke the anchors.

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.)

@simpleqt simpleqt closed this Aug 25, 2026
@simpleqt
simpleqt deleted the fix-docs-landing-links branch August 25, 2026 02:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:docs Documentation and Markdown only area:frontend Next.js frontend under frontend/ risk:low Low risk: docs / i18n / assets only size/S PR changes 20-100 lines

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants