feat: add local link check reports and baseline workflow#761
Open
feat: add local link check reports and baseline workflow#761
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds a local broken-link checking workflow (including report artifacts), removes the deprecated “script-course” docs/blog series, and updates a set of documentation links to reduce dead links and false positives during link checking.
Changes:
- Added local link-check tooling (
check-urls.sh, report processing + comparison scripts) and checked in baseline report artifacts underwebsite/reports/link-check/. - Removed the “script-course” doc series and the corresponding “intro-to-script-*” blog posts, with navigation/config updates to match.
- Performed targeted link cleanups across several docs pages.
Reviewed changes
Copilot reviewed 46 out of 46 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
website/sidebars.js |
Removes the “Script Development Course” category from the sidebar. |
website/reports/link-check/unresolved-known.json |
Adds generated artifact for unresolved known failures. |
website/reports/link-check/summary.json |
Adds generated run summary artifact. |
website/reports/link-check/report.md |
Adds human-readable link-check report artifact. |
website/reports/link-check/recovered.json |
Adds generated artifact for recovered links. |
website/reports/link-check/new-failures.json |
Adds generated artifact for newly failing links. |
website/reports/link-check/known-failures.json |
Adds baseline file for accepted failures. |
website/reports/link-check/history.jsonl |
Adds historical log of link-check runs. |
website/reports/link-check/dead-links.json |
Adds processed “current failures” artifact. |
website/reports/link-check/dead-links-raw.json |
Adds raw lychee JSON output artifact. |
website/package.json |
Adds link:check / link:report scripts for local link-check workflow. |
website/docusaurus.config.js |
Updates nav active regex to remove script-course routing. |
website/docs/script/vm-version.mdx |
Updates MOP reference links. |
website/docs/script/rust/rust-api-error.mdx |
Updates syscall source link to a stable tag reference. |
website/docs/script/fuzzing-ckb-scripts.mdx |
Updates GitHub links (repository/branch targets). |
website/docs/script-course/intro-to-script-9.md |
Removes deprecated script-course lesson content. |
website/docs/script-course/intro-to-script-6.md |
Removes deprecated script-course lesson content. |
website/docs/script-course/intro-to-script-5.md |
Removes deprecated script-course lesson content. |
website/docs/script-course/intro-to-script-4.md |
Removes deprecated script-course lesson content. |
website/docs/script-course/intro-to-script-2.md |
Removes deprecated script-course lesson content. |
website/docs/script-course/intro-to-script-10.md |
Removes deprecated script-course lesson content. |
website/docs/script-course/intro-to-script-1.md |
Removes deprecated script-course lesson content. |
website/docs/node/run-light-client-node.mdx |
Cleans up prerequisites (removes Xcode link). |
website/docs/node/run-a-node-over-tor.mdx |
Updates Tor bridge guidance link. |
website/docs/mining/guide.mdx |
Removes a broken vendor link from miner purchasing options. |
website/docs/history-and-hard-forks/rethinking-fork.mdx |
Replaces shortened/tracking links with direct canonical references. |
website/docs/assets-token-standards/spore-protocol.md |
Updates the RFC link target for CKB cryptoeconomics reference. |
website/blog/intro-to-script-9.md |
Removes deprecated blog post content. |
website/blog/intro-to-script-6.md |
Removes deprecated blog post content. |
website/blog/intro-to-script-5.md |
Removes deprecated blog post content. |
website/blog/intro-to-script-4.md |
Removes deprecated blog post content. |
website/blog/intro-to-script-2.md |
Removes deprecated blog post content. |
website/blog/intro-to-script-10.md |
Removes deprecated blog post content. |
website/blog/intro-to-script-1.md |
Removes deprecated blog post content. |
website/.prettierignore |
Excludes link-check history JSONL from formatting. |
scripts/process-link-results.js |
Adds post-processing of raw lychee results into structured artifacts + history. |
scripts/convert-github-urls.js |
Improves GitHub URL → API URL conversion to reduce false positives. |
scripts/compare-link-report.js |
Adds comparison against baseline (known-failures.json) and report generation. |
scripts/check-urls.sh |
Expands link-check script (token redaction, env config, JSON output, processing). |
README.md |
Documents the local link-check workflow and artifact meanings. |
Comments suppressed due to low confidence (1)
website/reports/link-check/history.jsonl:10
history.jsonldoes not include an entry corresponding to the committedsummary.json.runAt(2026-05-06T09:30:59Z) /report.mdgeneration time, which indicates the historical log is out of sync with the latest report artifacts. If these files are meant to be generated together, please re-run and commit a consistenthistory.jsonlthat includes the latest run.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
12
to
16
| "gen-term": "node scripts/generate-key-terms.mjs", | ||
| "fmt": "prettier --write . --ignore-path .prettierignore", | ||
| "link:check": "../scripts/check-urls.sh", | ||
| "link:report": "node ../scripts/compare-link-report.js", | ||
| "publish-gh-pages": "docusaurus-publish", |
Comment on lines
96
to
+101
|
|
||
| 1. Install [lychee](https://github.com/lycheeverse/lychee). | ||
| 2. Build the website: `cd website && yarn build`. | ||
| 3. Run the script: `./scripts/check-urls.sh`. | ||
| 3. Run the check: `cd website && yarn link:check`. | ||
| 4. Review results: `cd website && yarn link:report`. | ||
|
|
| LINK_CHECK_ACCEPT=${LINK_CHECK_ACCEPT:-"200..=299,403"} | ||
| GITHUB_TOKEN=${GITHUB_TOKEN:-""} | ||
|
|
||
| cd website |
Comment on lines
+43
to
+64
| LYCHEE_CMD="lychee --config .lychee.toml --cache-exclude-status=\"400..=699\" --format json --output reports/link-check/dead-links-raw.json" | ||
|
|
||
| if [ -n "$GITHUB_TOKEN" ]; then | ||
| LYCHEE_CMD="$LYCHEE_CMD --header \"Authorization: Bearer $GITHUB_TOKEN\"" | ||
| fi | ||
|
|
||
| # Override config with environment variables | ||
| LYCHEE_CMD="$LYCHEE_CMD --max-concurrency $LINK_CHECK_CONCURRENCY" | ||
| LYCHEE_CMD="$LYCHEE_CMD --timeout $LINK_CHECK_TIMEOUT" | ||
| LYCHEE_CMD="$LYCHEE_CMD --max-retries $LINK_CHECK_RETRIES" | ||
| LYCHEE_CMD="$LYCHEE_CMD --accept \"$LINK_CHECK_ACCEPT\"" | ||
|
|
||
| echo "🚀 Running link check with concurrency=$LINK_CHECK_CONCURRENCY, timeout=${LINK_CHECK_TIMEOUT}s, retries=$LINK_CHECK_RETRIES..." | ||
| DISPLAY_CMD="$LYCHEE_CMD" | ||
| if [ -n "$GITHUB_TOKEN" ]; then | ||
| DISPLAY_CMD="${DISPLAY_CMD//$GITHUB_TOKEN/***REDACTED***}" | ||
| fi | ||
| echo "Command: $DISPLAY_CMD build" | ||
|
|
||
| # Run lychee and capture both output and exit code | ||
| set +e | ||
| eval "$LYCHEE_CMD build" 2>&1 | grep --color=never -v 'InvalidPathToUri' |
Comment on lines
+14
to
24
| # Pre-flight checks | ||
| echo "🔍 Pre-flight checks..." | ||
| if ! command -v lychee &> /dev/null; then | ||
| echo "❌ Error: lychee is not installed. Please install it first: https://github.com/lycheeverse/lychee" | ||
| exit 1 | ||
| fi | ||
|
|
||
| if ! command -v node &> /dev/null; then | ||
| echo "❌ Error: node is not installed." | ||
| exit 1 | ||
| fi |
Comment on lines
+1
to
+20
| { | ||
| "total": 250, | ||
| "successful": 236, | ||
| "unknown": 0, | ||
| "unsupported": 0, | ||
| "timeouts": 0, | ||
| "redirects": 0, | ||
| "excludes": 0, | ||
| "errors": 14, | ||
| "cached": 0, | ||
| "success_map": {}, | ||
| "error_map": { | ||
| "build/github-api-urls.txt": [ | ||
| { | ||
| "url": "https://api.github.com/repos/nervosnetwork/molecule/contents/docs/encoding_spec.md?ref=master", | ||
| "status": { | ||
| "text": "Rejected status code (this depends on your \"accept\" configuration)", | ||
| "code": 429 | ||
| } | ||
| }, |
Comment on lines
+1
to
+7
| { | ||
| "runAt": "2026-05-06T09:30:59Z", | ||
| "scannedTotal": 250, | ||
| "failedTotal": 0, | ||
| "newFailedTotal": 0, | ||
| "recoveredTotal": 0 | ||
| } |
Comment on lines
+34
to
+43
| Object.entries(rawResults.error_map).forEach(([source, errors]) => { | ||
| errors.forEach(error => { | ||
| deadLinks.push({ | ||
| url: error.url, | ||
| status: error.status?.code || 'unknown', | ||
| sourceHint: source, | ||
| firstSeenAt: new Date().toISOString(), | ||
| lastSeenAt: new Date().toISOString(), | ||
| note: error.status?.text || null | ||
| }); |
|
|
||
| - [Rust (≥v.1.71.1)](https://www.rust-lang.org/tools/install) | ||
| - [XCode](https://developer.apple.com/xcode/resources/) (MacOs only) | ||
| - XCode (MacOs only) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR introduces a local broken-link workflow, removes deprecated script-course content, and applies a full round of link cleanup based on the branch diff against develop.
Scope (based on PR diff)
1) Link-check workflow and reports
2) Content cleanup/removal
3) Link fixes in docs
Targeted link fixes were applied in:
Review Guide (most important: manually verify link replacements)
Please prioritize this section first.
Direct Review Links (PR diff pages)
Use these links to jump directly to each changed file in the PR review page:
Validation
Commits in this PR