fix(docs): resolve repository links with a Markdown plugin by ooooo-create · Pull Request #315 · redai-studio/Relax

ooooo-create · 2026-09-14T13:49:56Z

What

Fix source navigation in the deployed documentation with a small Markdown plugin. Relative repository links such as ../../../relax/entrypoints/train.py resolve to GitHub source URLs instead of invalid site URLs ending in train.py.html.

Why

Documentation needs to link to repository files and directories while preserving normal navigation between documentation pages.

Fixes #313

How

Register the plugin in markdown.config and rewrite links before VitePress applies HTML normalization. Use GitHub blob URLs for files and tree URLs for directories, preserving query strings, fragments, and VitePress external-link attributes.
Configure repo, branch, repoRoot, and docsRoot explicitly. The site configuration derives an absolute repository root from import.meta.url and passes docsRoot: 'docs', so source links remain independent of the command's working directory. The plugin resolves relative documentation paths against repoRoot and also accepts absolute paths and nested documentation directories without depending on VitePress's internal configuration global.
Resolve relative source links against env.realPath ?? env.path, so page route rewrites do not change their filesystem base.
Warn about missing or inaccessible targets only after confirming they are inside the repository and outside the documentation directory. Warnings include the source document, original link, and failure reason; they do not fail the build.

Testing

pre-commit run --all-files --show-diff-on-failure passes.
node_modules/.bin/vitepress build docs passes with VitePress 1.6.4.
Verified all 98 source links in the generated English and Chinese pages.
Used the actual VitePress Markdown renderer to verify rewritten paths, the env.path fallback, file/directory links, missing JSON targets, filesystem errors, warning exclusions, and external-link attributes.
Built the real site from /tmp using an absolute site path. Exercised nested relative and absolute documentation roots with an absolute repository root from different working directories using the actual Markdown renderer.

The build reports three existing broken links to root-level DOCS_GUIDE.md and DOCUMENTATION_COMPLETE.md; those documents are outside this change. Python and multi-node GPU integration tests were not run because this change only affects documentation rendering. No new dependencies or Markdown content changes.

Type of Change

Bug fix (non-breaking change that fixes an issue)
CI/CD or build changes

Screenshots / Logs

Generated source links include:

https://github.com/redai-studio/Relax/blob/main/relax/entrypoints/train.py
https://github.com/redai-studio/Relax/tree/main/relax/engine/rollout

Copilot

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

rai-studio-bot · 2026-09-14T13:59:37Z

Nyanpasu 审查看板

审查状态： ✅ 已通过

审查版本： 015dbeddf3c4cbd621342ea0405f5a6a36612209

本次重构移除对 VitePress 内部全局 VITEPRESS_CONFIG 的依赖（回应 @SigureMo 意见）：改为由配置文件位置推导 repoRoot（fileURLToPath(new URL('../..', import.meta.url))）并显式传入 docsRoot: 'docs'，链接改写逻辑保持不变。本地以 VitePress 1.6.4 构建通过并复验：文件相对链接生成 blob/main URL、目录生成 tree/main URL，站内文档链接仍解析为 .html，生成结果与上一版一致。未发现需修改的问题。仅涉及文档渲染，未运行需多节点 GPU 的集成测试。

没有未解决的审查问题。

^{Powered by Nyanpasu with claude-opus-5-google[1m] medium, please check the suggestions carefully.}

rai-studio-bot

已完成对 3a5545839f043d5efae4910ab47d4880b6445df0 的审查，可以合入。文档构建和后处理通过，中英文架构页各 18 个仓库链接及 9 个链接边界用例验证通过，站内链接保持正常；4 项 CI 检查均通过。本次仅涉及文档配置，未运行需多节点 GPU 的集成测试。

^{Powered by Nyanpasu with gpt-6-astra medium, please check the suggestions carefully.}

# 🐛 Bug Fix - Rewrite relative Markdown links to existing repository files outside docs/ before VitePress applies HTML link normalization. - Use GitHub blob/main URLs for files and tree/main URLs for directories, preserving query strings and fragments. - Keep documentation links and missing or out-of-repository targets unchanged. ## Validation - Run pre-commit run --all-files --show-diff-on-failure successfully. - Build the VitePress site and verify the generated source links in both locales. - Confirm the train.py file and rollout directory URLs are accessible on GitHub. Fixes redai-studio#313

Copilot

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

# 🐛 Bug Fix - Resolve repository links against the original Markdown path when VitePress rewrites page routes, falling back to the rendered path when needed. - Warn about missing or inaccessible targets inside the repository and outside the documentation directory without failing the documentation build. # ♻️ Refactor - Extract source-link conversion into a small Markdown plugin configured with the repository URL, branch, and absolute VitePress source directory. - Keep access to VitePress's internal resolved configuration in the site config and document the repository-parent directory convention. - Preserve file and directory URLs, query strings, fragments, external-link attributes, and normal documentation link rendering. ## Validation - Pass pre-commit run --all-files --show-diff-on-failure. - Build the documentation with VitePress 1.6.4 and verify 98 source links across English and Chinese pages. - Exercise rewritten paths, missing JSON targets, filesystem errors, and warning exclusions with the actual VitePress Markdown renderer. Refs redai-studio#313

SigureMo · 2026-09-17T15:00:25Z

    math: true,
    config(md) {
+      // VitePress exposes its resolved config through this internal global.
+      const { srcDir } = (globalThis as typeof globalThis & { VITEPRESS_CONFIG: SiteConfig }).VITEPRESS_CONFIG


这块要是 internal 不如直接在下面写死了，比如 docs

rai-studio-bot

本次将实现重构为独立的 Markdown 插件（docs/.vitepress/plugins/source-links.ts）并在 config.mts 中注册，逻辑与既有实现等价且更清晰。本地以 VitePress 1.6.4 执行 vitepress build docs 通过并已验证：

仓库文件相对链接生成 blob/main URL、目录生成 tree/main URL；站内文档链接仍解析为 .html。
越界（../ 逃出仓库）、指向 docs/ 内部、以及缺失目标均按预期回退为原链接；缺失/异常目标仅 console.warn，不阻断构建。
构建告警中的根目录 DOCS_GUIDE.md、DOCUMENTATION_COMPLETE.md 为既有失效链接，不在本次改动范围。

未发现需修改的问题。仅涉及文档渲染，未运行需多节点 GPU 的集成测试。可以合入。

^{Powered by Nyanpasu with claude-opus-5-google[1m] medium, please check the suggestions carefully.}

# ♻️ Refactor - Pass independent repository and documentation roots to the source-link plugin instead of reading VitePress's internal configuration global. - Derive the site's absolute repository root from import.meta.url and resolve docsRoot relative to it, keeping builds independent of the working directory. - Support nested and absolute documentation roots without assuming the docs directory is a direct child of the repository. ## Validation - Run pre-commit checks across all files. - Build the VitePress 1.6.4 site from /tmp and verify all 98 source links in the generated English and Chinese pages. - Exercise relative and absolute documentation roots from multiple working directories with the actual VitePress Markdown renderer.

rai-studio-bot

本次重构移除了对 VitePress 内部全局 VITEPRESS_CONFIG 的依赖（回应 @SigureMo 的意见）：改为由配置文件自身位置推导 repoRoot（fileURLToPath(new URL('../..', import.meta.url))）并显式传入 docsRoot: 'docs'。toSourceUrl 链接改写逻辑保持不变。

本地以 VitePress 1.6.4 执行 vitepress build docs 通过并复验：仓库文件相对链接生成 blob/main URL、目录生成 tree/main URL，站内文档链接仍解析为 .html，生成链接数量与内容与上一版一致。

未发现需修改的问题。仅涉及文档渲染，未运行需多节点 GPU 的集成测试。可以合入。

^{Powered by Nyanpasu with claude-opus-5-google[1m] medium, please check the suggestions carefully.}

SigureMo

LGTMeow

ooooo-create requested review from NINGBENZHE and Yangruipis as code owners September 14, 2026 13:49

Copilot AI lite review requested due to automatic review settings September 14, 2026 13:49

Copilot AI reviewed Sep 14, 2026

rai-studio-bot approved these changes Sep 14, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings September 15, 2026 14:37

ooooo-create force-pushed the fix/docs-source-links-313 branch from 3a55458 to 96945c6 Compare September 15, 2026 14:37

Copilot AI reviewed Sep 15, 2026

SigureMo and others added 2 commits September 17, 2026 19:49

Merge branch 'main' into fix/docs-source-links-313

d4e7fa6

ooooo-create changed the title ~~fix(docs): fix relative repo links in built pages~~ fix(docs): resolve repository links with a Markdown plugin Sep 17, 2026

ooooo-create requested a review from rai-studio-bot September 17, 2026 14:58

SigureMo reviewed Sep 17, 2026

View reviewed changes

rai-studio-bot approved these changes Sep 17, 2026

View reviewed changes

SigureMo approved these changes Sep 17, 2026

View reviewed changes

SigureMo merged commit 4cb07d8 into redai-studio:main Sep 17, 2026
5 checks passed

Navigation Menu

fix(docs): resolve repository links with a Markdown plugin - #315

fix(docs): resolve repository links with a Markdown plugin#315
SigureMo merged 4 commits into
redai-studio:mainfrom
ooooo-create:fix/docs-source-links-313

ooooo-create commented Sep 14, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

rai-studio-bot commented Sep 14, 2026 •

edited

Loading

Uh oh!

rai-studio-bot left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

SigureMo Sep 17, 2026

Uh oh!

rai-studio-bot left a comment

Uh oh!

rai-studio-bot left a comment

Uh oh!

SigureMo left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

ooooo-create commented Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

How

Testing

Type of Change

Screenshots / Logs

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

rai-studio-bot commented Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Nyanpasu 审查看板

Uh oh!

rai-studio-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

SigureMo Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

rai-studio-bot left a comment

Choose a reason for hiding this comment

Uh oh!

rai-studio-bot left a comment

Choose a reason for hiding this comment

Uh oh!

SigureMo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ooooo-create commented Sep 14, 2026 •

edited

Loading

rai-studio-bot commented Sep 14, 2026 •

edited

Loading