fix(site): restore generated-site link checks#562
Conversation
Signed-off-by: spencercjh <jiahao.cai@dynamia.ai>
Signed-off-by: spencercjh <jiahao.cai@dynamia.ai>
Signed-off-by: spencercjh <jiahao.cai@dynamia.ai>
Signed-off-by: spencercjh <jiahao.cai@dynamia.ai>
✅ Deploy Preview for project-hami ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
📝 WalkthroughWalkthroughThis PR replaces the CI/npm link-checking approach with a new ChangesLink Check Tooling and Site URL Config
Relative URL Migration and Content Metadata
Estimated code review effort: 2 (Simple) | ~15 minutes Possibly related PRs
Suggested labels: Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Signed-off-by: spencercjh <jiahao.cai@dynamia.ai>
|
@rootsongjc I will fix all the problems you raised. Thanks for reviewing. The main point is the correct link check. It still does not work on the real ci env, when I finished it I will make the PR ready for review. |
Signed-off-by: spencercjh <jiahao.cai@dynamia.ai>
Signed-off-by: spencercjh <jiahao.cai@dynamia.ai>
Signed-off-by: spencercjh <jiahao.cai@dynamia.ai>
|
/assign @windsonsea |
|
/assign @rootsongjc |
|
[APPROVALNOTIFIER] This PR is APPROVED Approval requirements bypassed by manually added approval. This pull-request has been approved by: spencercjh The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 10
🧹 Nitpick comments (4)
.github/workflows/docs-health.yml (1)
35-41: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick winConsider a step timeout for the link-check step.
check-links.shstarts a background server and waits up to 60s for readiness, then relies onkill/waitin itsEXITtrap for cleanup. If the server process doesn't terminate cleanly (see orphaned-process concern raised inscripts/check-links.sh), the step could hang until the job-level default timeout (6 hours) is hit, wasting CI runner time. Adding atimeout-minutesto this step bounds the blast radius.Add a step timeout
- name: Broken Internal Link Check + timeout-minutes: 10 run: bash scripts/check-links.sh🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/docs-health.yml around lines 35 - 41, The Broken Internal Link Check step can hang if scripts/check-links.sh leaves the background server running, so add a step-level timeout to bound the runtime. Update the workflow step named Broken Internal Link Check in docs-health.yml to use a timeout setting so the job fails fast instead of waiting for the default runner timeout, keeping the link-check step isolated from orphaned-process issues in check-links.sh.package.json (2)
26-26: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winInline
VAR=valueenv syntax breaks on native Windows shells.
DOCUSAURUS_SITE_URL=http://127.0.0.1:3000 npm run builduses POSIX-only env-var assignment syntax, which fails on Windowscmd.exe/PowerShell (outside WSL/Git Bash). If this project supports Windows contributors running npm scripts natively,npm run check-links(and nowcheck:all, which depends on it) would break there.Cross-platform alternative using cross-env
- "check-links": "DOCUSAURUS_SITE_URL=http://127.0.0.1:3000 npm run build && bash scripts/check-links.sh", + "check-links": "cross-env DOCUSAURUS_SITE_URL=http://127.0.0.1:3000 npm run build && bash scripts/check-links.sh",🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@package.json` at line 26, The check-links npm script uses POSIX-only inline env assignment, which breaks native Windows shells. Update the package.json script for check-links to use a cross-platform env mechanism (for example, the existing npm script wiring with cross-env) so DOCUSAURUS_SITE_URL is set correctly before npm run build. Keep the change localized to the check-links entry so dependent scripts like check:all continue to work everywhere.
27-27: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win
check:allnow runs a full link check, not just a build — verify AGENTS.md docs are updated accordingly.AGENTS.md (per the upstream-contract context) describes
check:allaslint && format:check && build. This now transitively includescheck-links(a full site build + local server + linkinator crawl), which is materially heavier and adds a runtime dependency onnpx sirv-cli/linkinator. This is an intentional and reasonable change per the PR's goal, but the docs should reflect it.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@package.json` at line 27, Update the AGENTS.md guidance for check:all to match the new command flow in package.json: check:all now runs lint, format:check, and check-links instead of a build-only step. Make sure the docs mention that check-links performs a full site build plus local server/link crawl and therefore adds the sirv-cli and linkinator runtime dependency, so the description of check:all stays accurate.scripts/check-links.sh (1)
1-86: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAGENTS.md description of
npm run check-links/check:allis now stale.Per the upstream contract snippet, AGENTS.md documents
check-linksas "build + linkinator on./build" andcheck:allas "lint && format:check && build". With this change,check-linksinstead builds, serves the site locally, and crawls it live via HTTP, andcheck:allnow transitively runs the full link check rather than justbuild. Contributors following AGENTS.md would have an inaccurate mental model of what these commands do (e.g., expecting no network/server activity, or a plain build without link validation).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/check-links.sh` around lines 1 - 86, Update the AGENTS.md documentation for the `check-links` and `check:all` commands because their behavior changed in `check-links.sh`. Describe `check-links` as building the site, serving `build` locally via HTTP, and running linkinator against the live server, and note that `check:all` now includes the full link check transitively. Use the command names `check-links` and `check:all` so contributors can find the updated contract quickly.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@blog/hami-core-adopted-by-nvidia-kai-scheduler/index.md`:
- Line 51: The phrase in the blog copy should be hyphenated as open-source
rather than open source. Update the sentence in the markdown content near the
HAMi accelerator coverage paragraph so the wording reads naturally and
consistently, keeping the rest of the sentence unchanged.
In `@blog/hami-v2-9-0-release/index.md`:
- Line 209: The release note links currently use raw path text, which hurts
readability; update the affected markdown in the release note to use descriptive
anchor text instead of exposing the relative URL. Keep the same targets, but
change the link labels in the installation references and any other matching
instances in this document so readers can scan the note without seeing bare
paths.
In `@i18n/zh/docusaurus-plugin-content-blog/hami-cncf-incubating/index.md`:
- Line 19: The link in this blog content points Chinese readers to the default
docs locale instead of the Chinese docs page. Update the “支持设备列表” href in this
Markdown file to use the zh docs path, matching the existing Chinese routing
convention (for example, the device-supported page under /zh/docs).
In `@i18n/zh/docusaurus-plugin-content-docs/version-v2.6.0/releases.md`:
- Line 56: The localized release note link is pointing to the default docs route
instead of the Chinese docs tree. Update the link in the zh release content to
use the localized path for the cherry-picks guide, keeping it within the zh
documentation route. Locate the markdown in the releases content that references
the contributor cherry-picks docs and change only that target to the zh version.
In `@i18n/zh/docusaurus-plugin-content-docs/version-v2.9.0/releases.md`:
- Line 54: The link in the zh release note still points to the default locale,
so update the reference in the releases markdown to use the Chinese docs route.
Locate the existing markdown link in the release notes content and change it to
the zh-prefixed contributor/cherry-picks page so the snapshot stays within the
Chinese locale.
In `@scripts/check-links.sh`:
- Around line 5-7: The link-check setup in check-links.sh relies on separate
LINK_CHECK_HOST and LINK_CHECK_PORT defaults that can drift from
DOCUSAURUS_SITE_URL, causing internal absolute URLs to be misclassified. Update
the root_url construction and related internal host logic to derive host/port
from DOCUSAURUS_SITE_URL as the single source of truth, and ensure the same
source is used wherever the defaults are referenced so the behavior stays
consistent in check-links.sh and docs-health.yml.
In `@versioned_docs/version-v2.5.0/releases.md`:
- Line 63: The link text in releases.md is too generic and should be replaced
with descriptive text. Update the markdown sentence in the release note so the
reference to the cherry-pick usage docs uses meaningful anchor text instead of
“here,” keeping the same target and ensuring the wording around the cherry-pick
process remains clear.
In `@versioned_docs/version-v2.5.1/releases.md`:
- Line 63: The release note line uses vague link text, which triggers MD059 and
hurts readability. Update the Markdown in the releases doc so the link from the
cherry-pick sentence uses descriptive text instead of “here,” and keep the
target pointing to the cherry-picks contributor guide.
In `@versioned_docs/version-v2.6.0/releases.md`:
- Line 63: The release note sentence uses non-descriptive anchor text (“here”),
which triggers the markdown lint rule and hurts readability. Update the sentence
in the releases documentation to replace the generic link text with a meaningful
description that matches the target docs, keeping the existing cherry-pick
guidance and linking to the same cherry-picks page via a more descriptive
phrase.
In `@versioned_docs/version-v2.7.0/releases.md`:
- Line 63: The sentence in the releases doc uses non-descriptive link text,
which triggers MD059 and hurts scanability. Update the link in the release note
text to use descriptive anchor text instead of “here,” keeping the existing
destination and wording around the contributor cherry-pick script reference in
the releases content.
---
Nitpick comments:
In @.github/workflows/docs-health.yml:
- Around line 35-41: The Broken Internal Link Check step can hang if
scripts/check-links.sh leaves the background server running, so add a step-level
timeout to bound the runtime. Update the workflow step named Broken Internal
Link Check in docs-health.yml to use a timeout setting so the job fails fast
instead of waiting for the default runner timeout, keeping the link-check step
isolated from orphaned-process issues in check-links.sh.
In `@package.json`:
- Line 26: The check-links npm script uses POSIX-only inline env assignment,
which breaks native Windows shells. Update the package.json script for
check-links to use a cross-platform env mechanism (for example, the existing npm
script wiring with cross-env) so DOCUSAURUS_SITE_URL is set correctly before npm
run build. Keep the change localized to the check-links entry so dependent
scripts like check:all continue to work everywhere.
- Line 27: Update the AGENTS.md guidance for check:all to match the new command
flow in package.json: check:all now runs lint, format:check, and check-links
instead of a build-only step. Make sure the docs mention that check-links
performs a full site build plus local server/link crawl and therefore adds the
sirv-cli and linkinator runtime dependency, so the description of check:all
stays accurate.
In `@scripts/check-links.sh`:
- Around line 1-86: Update the AGENTS.md documentation for the `check-links` and
`check:all` commands because their behavior changed in `check-links.sh`.
Describe `check-links` as building the site, serving `build` locally via HTTP,
and running linkinator against the live server, and note that `check:all` now
includes the full link check transitively. Use the command names `check-links`
and `check:all` so contributors can find the updated contract quickly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 179cf258-687e-4bb6-9fb2-9de3dc860ab8
📒 Files selected for processing (45)
.github/workflows/docs-health.yml.gitignoreblog/hami-at-kubecon-eu-2026/index.mdblog/hami-cncf-incubating/index.mdblog/hami-core-adopted-by-nvidia-kai-scheduler/index.mdblog/hami-meetup-beijing-2025/index.mdblog/hami-meetup-shanghai-2025/index.mdblog/hami-meetup-shenzhen-2026/index.mdblog/hami-v2-9-0-release/index.mdblog/kubecon-india-2026-recap/index.mddocs/installation/aws-installation.mddocs/releases.mddocusaurus.config.jsi18n/zh/docusaurus-plugin-content-blog/2024-12-18-support-blog-post/index.mdi18n/zh/docusaurus-plugin-content-blog/2024-12-31-post/index.mdi18n/zh/docusaurus-plugin-content-blog/hami-at-kubecon-eu-2026/index.mdi18n/zh/docusaurus-plugin-content-blog/hami-cncf-incubating/index.mdi18n/zh/docusaurus-plugin-content-blog/hami-core-adopted-by-nvidia-kai-scheduler/index.mdi18n/zh/docusaurus-plugin-content-blog/hami-meetup-beijing-2025/index.mdi18n/zh/docusaurus-plugin-content-blog/hami-v2-9-0-release/index.mdi18n/zh/docusaurus-plugin-content-blog/kubecon-india-2026-recap/index.mdi18n/zh/docusaurus-plugin-content-blog/tags.ymli18n/zh/docusaurus-plugin-content-docs-tutorials/current/tags.ymli18n/zh/docusaurus-plugin-content-docs/current/installation/aws-installation.mdi18n/zh/docusaurus-plugin-content-docs/current/releases.mdi18n/zh/docusaurus-plugin-content-docs/version-v2.5.0/releases.mdi18n/zh/docusaurus-plugin-content-docs/version-v2.5.1/releases.mdi18n/zh/docusaurus-plugin-content-docs/version-v2.6.0/releases.mdi18n/zh/docusaurus-plugin-content-docs/version-v2.7.0/installation/aws-installation.mdi18n/zh/docusaurus-plugin-content-docs/version-v2.7.0/releases.mdi18n/zh/docusaurus-plugin-content-docs/version-v2.8.0/installation/aws-installation.mdi18n/zh/docusaurus-plugin-content-docs/version-v2.8.0/releases.mdi18n/zh/docusaurus-plugin-content-docs/version-v2.9.0/installation/aws-installation.mdi18n/zh/docusaurus-plugin-content-docs/version-v2.9.0/releases.mdpackage.jsonscripts/check-links.shversioned_docs/version-v2.5.0/releases.mdversioned_docs/version-v2.5.1/releases.mdversioned_docs/version-v2.6.0/releases.mdversioned_docs/version-v2.7.0/installation/aws-installation.mdversioned_docs/version-v2.7.0/releases.mdversioned_docs/version-v2.8.0/installation/aws-installation.mdversioned_docs/version-v2.8.0/releases.mdversioned_docs/version-v2.9.0/installation/aws-installation.mdversioned_docs/version-v2.9.0/releases.md
| - **HAMi** ensures "once allocated, that is all you get, and you cannot take more" (the isolation layer). | ||
|
|
||
| Only by combining the two do you get true production-grade GPU sharing. HAMi supports NVIDIA GPUs, Huawei Ascend NPUs, Cambricon MLUs, Hygon DCUs, Kunlun XPUs, and many other heterogeneous accelerators, making it the open source solution with the broadest coverage in cloud-native GPU virtualization. For the full list of supported accelerators, see the [HAMi documentation](https://project-hami.io/docs/userguide/device-supported). | ||
| Only by combining the two do you get true production-grade GPU sharing. HAMi supports NVIDIA GPUs, Huawei Ascend NPUs, Cambricon MLUs, Hygon DCUs, Kunlun XPUs, and many other heterogeneous accelerators, making it the open source solution with the broadest coverage in cloud-native GPU virtualization. For the full list of supported accelerators, see the [HAMi documentation](/docs/userguide/device-supported). |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Hyphenate “open-source”.
open source should be hyphenated here; it reads better as open-source.
✏️ Suggested tweak
-... making it the open source solution with the broadest coverage in cloud-native GPU virtualization.
+... making it the open-source solution with the broadest coverage in cloud-native GPU virtualization.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Only by combining the two do you get true production-grade GPU sharing. HAMi supports NVIDIA GPUs, Huawei Ascend NPUs, Cambricon MLUs, Hygon DCUs, Kunlun XPUs, and many other heterogeneous accelerators, making it the open source solution with the broadest coverage in cloud-native GPU virtualization. For the full list of supported accelerators, see the [HAMi documentation](/docs/userguide/device-supported). | |
| Only by combining the two do you get true production-grade GPU sharing. HAMi supports NVIDIA GPUs, Huawei Ascend NPUs, Cambricon MLUs, Hygon DCUs, Kunlun XPUs, and many other heterogeneous accelerators, making it the open-source solution with the broadest coverage in cloud-native GPU virtualization. For the full list of supported accelerators, see the [HAMi documentation](/docs/userguide/device-supported). |
🧰 Tools
🪛 LanguageTool
[grammar] ~51-~51: Use a hyphen to join words.
Context: ...geneous accelerators, making it the open source solution with the broadest covera...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@blog/hami-core-adopted-by-nvidia-kai-scheduler/index.md` at line 51, The
phrase in the blog copy should be hyphenated as open-source rather than open
source. Update the sentence in the markdown content near the HAMi accelerator
coverage paragraph so the wording reads naturally and consistently, keeping the
rest of the sentence unchanged.
Source: Linters/SAST tools
| ``` | ||
|
|
||
| For complete installation documentation, refer to: [https://project-hami.io/docs/installation/online-installation](https://project-hami.io/docs/installation/online-installation) | ||
| For complete installation documentation, refer to: [/docs/installation/online-installation](/docs/installation/online-installation) |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use descriptive anchor text for these links.
The relative targets are fine, but rendering raw paths makes the release note harder to scan.
✏️ Suggested tweak
-For complete installation documentation, refer to: [/docs/installation/online-installation](/docs/installation/online-installation)
+For complete installation documentation, refer to the [installation guide](/docs/installation/online-installation)
-Website: [/](/)
+Website: [HAMi homepage](/)
-Documentation: [/docs/](/docs/)
+Documentation: [HAMi docs](/docs/)Also applies to: 242-242, 269-269
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@blog/hami-v2-9-0-release/index.md` at line 209, The release note links
currently use raw path text, which hurts readability; update the affected
markdown in the release note to use descriptive anchor text instead of exposing
the relative URL. Keep the same targets, but change the link labels in the
installation references and any other matching instances in this document so
readers can scan the note without seeing bare paths.
| HAMi 是面向 Kubernetes 的异构算力虚拟化与调度中间件，通过容器级硬隔离精细切分 GPU 显存与算力，让多个工作负载安全共享同一张加速器。项目由 [张潇](https://github.com/wawa0210)、[李孟轩](https://github.com/archlitchi) 等维护者发起，在 CNCF 治理下由全球开发者共建。 | ||
|
|
||
| 今天，HAMi 已被数百家组织采用，覆盖 NVIDIA、昇腾、寒武纪、海光、摩尔线程、燧原、昆仑芯、MetaX、AWS Neuron、Vastai 等十余种加速器（见[支持设备列表](https://project-hami.io/docs/userguide/device-supported)），并以 [CNCF 案例研究](/zh/case-studies)的形式记录了招商银行、SNOW Corp.、蔚来、贝壳、DaoCloud、顺丰科技、PREP EDU 等的落地实践，横跨金融、汽车、出行、物流、教育与云服务。HAMi-core 已与 Kubernetes 默认调度器、[Volcano](https://github.com/volcano-sh/volcano/blob/master/docs/user-guide/how_to_use_gpu_sharing.md)、[Kueue](https://github.com/kubernetes-sigs/kueue)、[Koordinator](https://koordinator.sh/docs/user-manuals/device-scheduling-gpu-share-with-hami) 以及 [KAI Scheduler](/zh/blog/hami-core-adopted-by-nvidia-kai-scheduler) 完成集成。 | ||
| 今天，HAMi 已被数百家组织采用，覆盖 NVIDIA、昇腾、寒武纪、海光、摩尔线程、燧原、昆仑芯、MetaX、AWS Neuron、Vastai 等十余种加速器（见[支持设备列表](/docs/userguide/device-supported)），并以 [CNCF 案例研究](/zh/case-studies)的形式记录了招商银行、SNOW Corp.、蔚来、贝壳、DaoCloud、顺丰科技、PREP EDU 等的落地实践，横跨金融、汽车、出行、物流、教育与云服务。HAMi-core 已与 Kubernetes 默认调度器、[Volcano](https://github.com/volcano-sh/volcano/blob/master/docs/user-guide/how_to_use_gpu_sharing.md)、[Kueue](https://github.com/kubernetes-sigs/kueue)、[Koordinator](https://koordinator.sh/docs/user-manuals/device-scheduling-gpu-share-with-hami) 以及 [KAI Scheduler](/zh/blog/hami-core-adopted-by-nvidia-kai-scheduler) 完成集成。 |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Inspect zh blog posts for docs links that may need a /zh/ prefix.
rg -n '\]\(/docs/' i18n/zh/docusaurus-plugin-content-blogRepository: Project-HAMi/website
Length of output: 2430
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect site i18n/doc routing config and related zh docs link usage.
git ls-files docusaurus.config.* sidebars.* i18n/zh | sed -n '1,200p'
echo '--- docusaurus config outline ---'
ast-grep outline docusaurus.config.* --view expanded 2>/dev/null || true
echo '--- search for docsRouteBasePath / locale routeBasePath ---'
rg -n 'docsRouteBasePath|routeBasePath|defaultLocale|locales|i18n|/zh/docs|/docs/' docusaurus.config.* i18n/zh -g '!**/node_modules/**'Repository: Project-HAMi/website
Length of output: 50377
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Find the exact file listing the docs navigation or localization links.
fd -t f 'docusaurus.config.*|sidebars.*|doc.*' .Repository: Project-HAMi/website
Length of output: 1787
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo '--- docusaurus.config.js relevant sections ---'
sed -n '60,90p;210,290p' docusaurus.config.js
echo '--- custom docs plugin outline ---'
ast-grep outline src/plugins/docs/index.js --view expanded 2>/dev/null || true
echo '--- custom docs plugin search ---'
rg -n 'routeBasePath|docsRouteBasePath|currentLocale|/zh/docs|/docs' src/plugins/docs/index.js docusaurus.config.jsRepository: Project-HAMi/website
Length of output: 4997
Use the zh docs path here
This link sends Chinese readers to the default docs locale; the matching Chinese page exists at /zh/docs/userguide/device-supported.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@i18n/zh/docusaurus-plugin-content-blog/hami-cncf-incubating/index.md` at line
19, The link in this blog content points Chinese readers to the default docs
locale instead of the Chinese docs page. Update the “支持设备列表” href in this
Markdown file to use the zh docs path, matching the existing Chinese routing
convention (for example, the device-supported page under /zh/docs).
| - 补丁版本从发布分支创建。 | ||
| - 对于需要包含在补丁版本中的关键修复，PR 应始终首先合并到 master，然后再挑选到发布分支。PR 需要确保有发布说明撰写，这些描述将在下一个补丁版本中反映。 | ||
| PR 的挑选过程通过脚本执行。使用方法参见[此处](https://project-hami.io/docs/contributor/cherry-picks)。 | ||
| PR 的挑选过程通过脚本执行。使用方法参见[此处](/docs/contributor/cherry-picks)。 |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n 'cherry-picks' docs i18n/zh versioned_docsRepository: Project-HAMi/website
Length of output: 8386
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect the surrounding zh docs and compare link usage patterns.
sed -n '48,62p' i18n/zh/docusaurus-plugin-content-docs/version-v2.6.0/releases.md
printf '\n---\n'
sed -n '48,62p' i18n/zh/docusaurus-plugin-content-docs/current/releases.md
printf '\n---\n'
rg -n '\]\(/zh/docs/|/docs/' i18n/zh/docusaurus-plugin-content-docs/current i18n/zh/docusaurus-plugin-content-docs/version-v2.6.0 versioned_docs/version-v2.6.0
printf '\n---\n'
sed -n '1,80p' docusaurus.config.* 2>/dev/null || trueRepository: Project-HAMi/website
Length of output: 43959
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Look for the localized docs route structure and any explicit zh-prefixed internal links.
git ls-files | rg '(^|/)docusaurus\.config\.[jt]s$|^docusaurus\.config\.(js|ts|mjs|cjs)$|^sidebars.*|^i18n/zh/.*/cherry-picks\.md$|^versioned_docs/version-v2\.6\.0/contributor/cherry-picks\.md$'
printf '\n---\n'
rg -n '/zh/docs/contributor/cherry-picks|/docs/contributor/cherry-picks' i18n/zh versioned_docs docsRepository: Project-HAMi/website
Length of output: 4042
Use the zh docs route here /zh/docs/contributor/cherry-picks keeps readers in the localized docs tree.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@i18n/zh/docusaurus-plugin-content-docs/version-v2.6.0/releases.md` at line
56, The localized release note link is pointing to the default docs route
instead of the Chinese docs tree. Update the link in the zh release content to
use the localized path for the cherry-picks guide, keeping it within the zh
documentation route. Locate the markdown in the releases content that references
the contributor cherry-picks docs and change only that target to the zh version.
| - 分支名称将包含版本，例如 release-1.2。 | ||
| - 补丁版本从发布分支创建。 | ||
| - 对于需要包含在补丁版本中的关键修复，PR 应始终首先合并到 master，然后再挑选到发布分支。PR 需要确保有发布说明撰写，这些描述将在下一个补丁版本中反映。PR 的挑选过程通过脚本执行。使用方法参见[此处](https://project-hami.io/docs/contributor/cherry-picks)。 | ||
| - 对于需要包含在补丁版本中的关键修复，PR 应始终首先合并到 master，然后再挑选到发布分支。PR 需要确保有发布说明撰写，这些描述将在下一个补丁版本中反映。PR 的挑选过程通过脚本执行。使用方法参见[此处](/docs/contributor/cherry-picks)。 |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n 'cherry-picks' docs i18n/zh versioned_docsRepository: Project-HAMi/website
Length of output: 8386
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== docusaurus config ==\n'
fd -a 'docusaurus.config.*|sidebars.*' . | sed -n '1,20p'
printf '\n== zh docs link patterns ==\n'
rg -n --glob 'i18n/zh/**/*.md' --glob 'versioned_docs/**/*.md' '/zh/docs/|/docs/' i18n/zh versioned_docs docs | sed -n '1,120p'
printf '\n== cherry-picks doc front matter / path ==\n'
sed -n '1,40p' i18n/zh/docusaurus-plugin-content-docs/version-v2.9.0/contributor/cherry-picks.md
printf '\n---\n'
sed -n '1,40p' versioned_docs/version-v2.9.0/contributor/cherry-picks.md
printf '\n---\n'
sed -n '1,80p' i18n/zh/docusaurus-plugin-content-docs/version-v2.9.0/releases.md
printf '\n---\n'
sed -n '1,80p' versioned_docs/version-v2.9.0/releases.mdRepository: Project-HAMi/website
Length of output: 29570
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== docusaurus.config.js (relevant sections) ==\n'
rg -n 'i18n|defaultLocale|locales|docs:|routeBasePath|path:|localeConfigs|sidebarPath' docusaurus.config.js
printf '\n---\n'
sed -n '1,220p' docusaurus.config.jsRepository: Project-HAMi/website
Length of output: 6601
Use the zh docs route here.
/docs/contributor/cherry-picks points to the default locale; this zh snapshot has a Chinese contributor/cherry-picks page, so the link should stay under /zh/docs/....
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@i18n/zh/docusaurus-plugin-content-docs/version-v2.9.0/releases.md` at line
54, The link in the zh release note still points to the default locale, so
update the reference in the releases markdown to use the Chinese docs route.
Locate the existing markdown link in the release notes content and change it to
the zh-prefixed contributor/cherry-picks page so the snapshot stays within the
Chinese locale.
| host="${LINK_CHECK_HOST:-127.0.0.1}" | ||
| port="${LINK_CHECK_PORT:-3000}" | ||
| root_url="http://${host}:${port}" |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Host/port coupling between build-time DOCUSAURUS_SITE_URL and serve-time LINK_CHECK_HOST/LINK_CHECK_PORT is implicit and unvalidated.
The internal-vs-external host detection at Lines 27-29 only works because package.json's DOCUSAURUS_SITE_URL=http://127.0.0.1:3000 happens to match the LINK_CHECK_HOST/LINK_CHECK_PORT defaults (127.0.0.1/3000) used here and in docs-health.yml. If either value drifts independently in the future, absolute site URLs (canonical/OG tags) baked into the built HTML would no longer match internal_hosts, causing them to be silently classified as "external" and skipped from validation — reproducing exactly the "0 links scanned" bug this PR fixes, without any error or warning.
Consider deriving host/port directly from DOCUSAURUS_SITE_URL (single source of truth) instead of independent env vars, so drift is structurally impossible.
Suggested direction
-host="${LINK_CHECK_HOST:-127.0.0.1}"
-port="${LINK_CHECK_PORT:-3000}"
-root_url="http://${host}:${port}"
+site_url="${DOCUSAURUS_SITE_URL:-http://127.0.0.1:3000}"
+host="$(python3 -c "from urllib.parse import urlparse; print(urlparse('${site_url}').hostname)")"
+port="$(python3 -c "from urllib.parse import urlparse; print(urlparse('${site_url}').port or 80)")"
+root_url="${site_url%/}"Also applies to: 49-50
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@scripts/check-links.sh` around lines 5 - 7, The link-check setup in
check-links.sh relies on separate LINK_CHECK_HOST and LINK_CHECK_PORT defaults
that can drift from DOCUSAURUS_SITE_URL, causing internal absolute URLs to be
misclassified. Update the root_url construction and related internal host logic
to derive host/port from DOCUSAURUS_SITE_URL as the single source of truth, and
ensure the same source is used wherever the defaults are referenced so the
behavior stays consistent in check-links.sh and docs-health.yml.
| and then cherry-picked to the release branch. PRs need to be guaranteed to have a release note written and | ||
| these descriptions will be reflected in the next patch release. | ||
| The cherry-pick process of PRs is executed through the script. See usage [here](https://project-hami.io/docs/contributor/cherry-picks). | ||
| The cherry-pick process of PRs is executed through the script. See usage [here](/docs/contributor/cherry-picks). |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Replace “here” with descriptive link text.
The relative target is fine, but here is non-descriptive and hurts readability.
✏️ Suggested tweak
- The cherry-pick process of PRs is executed through the script. See usage [here](/docs/contributor/cherry-picks).
+ The cherry-pick process of PRs is executed through the script. See [cherry-pick usage](/docs/contributor/cherry-picks).📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| The cherry-pick process of PRs is executed through the script. See usage [here](/docs/contributor/cherry-picks). | |
| The cherry-pick process of PRs is executed through the script. See [cherry-pick usage](/docs/contributor/cherry-picks). |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 63-63: Link text should be descriptive
(MD059, descriptive-link-text)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@versioned_docs/version-v2.5.0/releases.md` at line 63, The link text in
releases.md is too generic and should be replaced with descriptive text. Update
the markdown sentence in the release note so the reference to the cherry-pick
usage docs uses meaningful anchor text instead of “here,” keeping the same
target and ensuring the wording around the cherry-pick process remains clear.
Source: Linters/SAST tools
| and then cherry-picked to the release branch. PRs need to be guaranteed to have a release note written and | ||
| these descriptions will be reflected in the next patch release. | ||
| The cherry-pick process of PRs is executed through the script. See usage [here](https://project-hami.io/docs/contributor/cherry-picks). | ||
| The cherry-pick process of PRs is executed through the script. See usage [here](/docs/contributor/cherry-picks). |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use descriptive link text.
here still trips MD059 and is hard to scan in rendered docs.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 63-63: Link text should be descriptive
(MD059, descriptive-link-text)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@versioned_docs/version-v2.5.1/releases.md` at line 63, The release note line
uses vague link text, which triggers MD059 and hurts readability. Update the
Markdown in the releases doc so the link from the cherry-pick sentence uses
descriptive text instead of “here,” and keep the target pointing to the
cherry-picks contributor guide.
Source: Linters/SAST tools
| and then cherry-picked to the release branch. PRs need to be guaranteed to have a release note written and | ||
| these descriptions will be reflected in the next patch release. | ||
| The cherry-pick process of PRs is executed through the script. See usage [here](https://project-hami.io/docs/contributor/cherry-picks). | ||
| The cherry-pick process of PRs is executed through the script. See usage [here](/docs/contributor/cherry-picks). |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use descriptive link text.
here still trips MD059 and is hard to scan in rendered docs.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 63-63: Link text should be descriptive
(MD059, descriptive-link-text)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@versioned_docs/version-v2.6.0/releases.md` at line 63, The release note
sentence uses non-descriptive anchor text (“here”), which triggers the markdown
lint rule and hurts readability. Update the sentence in the releases
documentation to replace the generic link text with a meaningful description
that matches the target docs, keeping the existing cherry-pick guidance and
linking to the same cherry-picks page via a more descriptive phrase.
Source: Linters/SAST tools
| and then cherry-picked to the release branch. PRs need to be guaranteed to have a release note written and | ||
| these descriptions will be reflected in the next patch release. | ||
| The cherry-pick process of PRs is executed through the script. See usage [here](https://project-hami.io/docs/contributor/cherry-picks). | ||
| The cherry-pick process of PRs is executed through the script. See usage [here](/docs/contributor/cherry-picks). |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use descriptive link text.
here still trips MD059 and is hard to scan in rendered docs.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 63-63: Link text should be descriptive
(MD059, descriptive-link-text)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@versioned_docs/version-v2.7.0/releases.md` at line 63, The sentence in the
releases doc uses non-descriptive link text, which triggers MD059 and hurts
scanability. Update the link in the release note text to use descriptive anchor
text instead of “here,” keeping the existing destination and wording around the
contributor cherry-pick script reference in the releases content.
Source: Linters/SAST tools
|
Merged, but one thing is still open. The mig casing fix only covers current and v2.7.0. v2.8.0 and v2.9.0 still say lowercase mig. v2.9.0 is the live version. Follow up here: #563 |
4 participants
Summary
linkinator ./build --skip '^https?://'path with a real generated-site crawl against a served buildscripts/check-links.shas the pure-linkinatororchestration entrypoint and wirecheck:all/docs-health.ymlthrough itDOCUSAURUS_SITE_URLoverrideable during link-check builds so canonical/og same-site absolute URLs resolve locallyWhy
The previous CI command looked green but actually scanned
0 links, so generated-site regressions could slip through. This PR makes the link check exercise the built site for real and fixes the broken routes it exposes on the current branch.Notes
scripts/check-links.shdoes not implement a custom checker; it only starts the static server, derives external-host skip rules from generated HTML, and invokeslinkinator.github, so this body is written directlyValidation
npm run check:allnpm run check-linksnpm run lintnpm run format:checkgh act workflow_dispatch -W .github/workflows/docs-health.yml -j check -P ubuntu-latest=catthehacker/ubuntu:act-latest --no-skip-checkoutSummary by CodeRabbit