Problem
The linkChecker CI job currently runs across the entire repo on every PR. This means any PR touching even one file fails CI if any page anywhere in the repo has a broken external link — including pages the PR never touched.
As of today, these broken links are failing every PR:
| File |
Broken link |
Error |
builder-cookbook/data-storage/retrieve-data.md |
saturn.tech |
Network error |
storage-providers/filecoin-deals/return-on-investment.md |
calc.filecoin.eu |
Network error |
storage-providers/basics/quickstart-guide.md |
calc.filecoin.eu |
Network error |
smart-contracts/fundamentals/the-fvm.md |
saturn.tech |
Network error |
smart-contracts/advanced/oracles.md |
eoracle.gitbook.io |
404 |
builder-cookbook/data-storage/store-data.md |
docs.lighthouse.storage |
404 |
basics/how-storage-works/storage-onramps.md |
singularity.storage, ramo.io |
525 / 404 |
storage-providers/infrastructure/network.md |
saturn.tech |
Network error |
reference/general/README.md |
ramo.io, singularity.storage |
404 / 525 |
smart-contracts/developing-contracts/solidity-libraries.md |
docs.0x.org |
404 |
storage-providers/filecoin-deals/auxiliary-services.md |
saturn.tech |
Network error |
basics/how-storage-works/filecoin-plus.md |
fidl.tech |
404 |
smart-contracts/advanced/multisig.md |
help.safe.global |
404 |
This is not a fair burden to place on contributors. A PR fixing docs on one page shouldn't be responsible for broken links across the entire repo.
Proposed Solution
1. PR link checker — scope to changed files only
Change the CI link check on PRs to only check files changed in the PR (e.g., using git diff --name-only against the base branch). This ensures PRs are only responsible for links on pages they actually touch.
2. Scheduled weekly link check — repo-wide
Add a weekly scheduled workflow (e.g., GitHub Actions schedule: cron) that runs the full repo-wide link check and automatically opens or updates an issue with the results. This keeps the repo's link health visible without blocking contributors.
3. Fix the current broken links (separate cleanup PR)
The 13 broken links above should be fixed or removed in a dedicated PR, independent of any feature work.
Problem
The linkChecker CI job currently runs across the entire repo on every PR. This means any PR touching even one file fails CI if any page anywhere in the repo has a broken external link — including pages the PR never touched.
As of today, these broken links are failing every PR:
builder-cookbook/data-storage/retrieve-data.mdsaturn.techstorage-providers/filecoin-deals/return-on-investment.mdcalc.filecoin.eustorage-providers/basics/quickstart-guide.mdcalc.filecoin.eusmart-contracts/fundamentals/the-fvm.mdsaturn.techsmart-contracts/advanced/oracles.mdeoracle.gitbook.iobuilder-cookbook/data-storage/store-data.mddocs.lighthouse.storagebasics/how-storage-works/storage-onramps.mdsingularity.storage,ramo.iostorage-providers/infrastructure/network.mdsaturn.techreference/general/README.mdramo.io,singularity.storagesmart-contracts/developing-contracts/solidity-libraries.mddocs.0x.orgstorage-providers/filecoin-deals/auxiliary-services.mdsaturn.techbasics/how-storage-works/filecoin-plus.mdfidl.techsmart-contracts/advanced/multisig.mdhelp.safe.globalThis is not a fair burden to place on contributors. A PR fixing docs on one page shouldn't be responsible for broken links across the entire repo.
Proposed Solution
1. PR link checker — scope to changed files only
Change the CI link check on PRs to only check files changed in the PR (e.g., using
git diff --name-onlyagainst the base branch). This ensures PRs are only responsible for links on pages they actually touch.2. Scheduled weekly link check — repo-wide
Add a weekly scheduled workflow (e.g., GitHub Actions
schedule: cron) that runs the full repo-wide link check and automatically opens or updates an issue with the results. This keeps the repo's link health visible without blocking contributors.3. Fix the current broken links (separate cleanup PR)
The 13 broken links above should be fixed or removed in a dedicated PR, independent of any feature work.