fix: repair stale documentation links and link-checker coverage#828
Conversation
- delete docs/bee/installation/verify.md, a draft placeholder whose body was just the filename and a stray Bee PR link - page was not referenced anywhere: absent from sidebars.js, unlinked from other docs, no redirect in docusaurus.config.mjs, and not indexed in llms.txt - removal drops one entry from the llms.txt coverage validator's missing-pages list Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Yejin Kelly Joo <yejinkellyjoo@gmail.com>
- resources-md: fix 404 by merging the removed examples/basic-static-website entry into the website entry, and switch all six ethersphere/examples links from the renamed master branch to main - resources-md: repoint retired desktop.ethswarm.org subdomain to ethswarm.org/build/desktop - build-from-source: update golang.org -> go.dev (URL and link text, x2) after the Go site rebrand - ai-agent-skills: update claude.com/claude-code -> claude.com/product/claude-code (x2) - jq: update jqlang.github.io/jq/ -> jqlang.org/ across getting-started, package-manager, shell-script, bee-api, and starting-a-test-network after jq moved to its own domain - community: repoint retired grants.ethswarm.org subdomain to the grants programme page, and point the Swarm 'awesome list' text to the internal /docs/references/awesome-list page instead of the generic awesome.re badge redirect - host-your-website: update the ENS support article to its new slug (same article id 12275979) - connectivity: replace the retired Microsoft KB 4028544 Defender Firewall article with its current Windows Security page - glossary: update gnosis.io/validators -> validategnosis.com after the Gnosis validators rebrand Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Yejin Kelly Joo <yejinkellyjoo@gmail.com>
- drop the trailing slash on the DISC entry (/docs/concepts/DISC/ -> /docs/concepts/DISC) so it matches the built URL; resolves the sole stale llms.txt entry - add Multi-Author Blog under 'Host websites on Swarm' - add Developer Resources under 'Build applications on Swarm' Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Yejin Kelly Joo <yejinkellyjoo@gmail.com>
- filter out @docusaurus/plugin-client-redirects meta-refresh stub pages when computing llms.txt build coverage, so old-URL forwards no longer count as "missing from llms.txt" - detect stubs by the http-equiv="refresh" marker in their build HTML - reduces recurring false-positive noise (missing pages 26 -> 4; only genuine navigation-landing intros remain) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Yejin Kelly Joo <yejinkellyjoo@gmail.com>
✅ Deploy Preview for test-twitter-preview-testing-3 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
GasperX93
left a comment
GasperX93
left a comment
There was a problem hiding this comment.
LGTM — verified every changed link resolves rather than eyeballing them.
Checked and confirmed:
- All 18 new links return 200 (go.dev, jqlang.org, new ENS slug, all 6
examples/tree/main/...paths, ethswarm.org/build/desktop, claude.com/product/claude-code, validategnosis.com, grants URL, and the 3 llms.txt targets). validategnosis.comis legit — "Gnosis Chain Validator," the current dedicated validator site.basic-static-websiteis a genuine 404 on bothmainandmaster— correct to remove.verify.mdis an orphaned stub, unreferenced insidebars.jsandllms.txt— safe to delete, no dangling nav.- New internal
/docs/references/awesome-listtarget resolves live (build-generated) — better than the old genericawesome.re. check_links.tsmeta-refresh skip is sound and well-commented.
One note (not blocking): most of the old links still 200 via redirect (jqlang.github.io/jq, the old ENS slug, master→main, desktop.ethswarm.org, claude.com/claude-code, grants.ethswarm.org, gnosis.io/validators) — so these are stale-link canonicalizations rather than dead-404 repairs; only basic-static-website and the retired MS Defender article were truly broken. Canonical URLs are more durable, so it's a net improvement either way. Nice cleanup.
crtahlin
left a comment
crtahlin
left a comment
There was a problem hiding this comment.
LGTM — approving. Reviewed the full diff, CI, and existing review. Clean, low-risk docs link-repair; every hunk matches its description and the link-checker fix targets the root cause of the llms.txt false positives. No blocking issues.
A couple of non-blocking notes for consideration:
-
scripts/check_links.ts—fs.readFileSync(htmlFile)now runs for every built doc page to test for the meta-refresh marker, not just candidates. Negligible for a build-time script, just noting it re-reads all built HTML as the docs set grows. -
static/llms.txt— the two added entries (/docs/develop/multi-author-blog,/docs/develop/resources) resolve 200 as build-generated pages rather than source.mdfiles in this diff. Confirmed live, so no dead entry — just flagging the dependency on build-time generation.
Nice, disciplined cleanup — good call documenting the verified false-positives (always-latest redirects, bot-blocked-but-live sites) that were deliberately left alone.
3 participants
What does this PR resolve? 🚀
Audit and repair of stale/broken links across the docs, plus a link-checker fix so its
llms.txtcoverage report stops flagging redirect stubs.concepts/DISCentry instatic/llms.txtand add two missing content pagesverify.mdplaceholder pagellms.txtcoverageDetails 📝
fix(docs)):ethersphere/exampleslinksmaster→mainand the deadbasic-static-websiteentry merged into thewebsiteexample;golang.org→go.dev;jqlang.github.io/jq→jqlang.org(5 files);claude.com/claude-code→/product/claude-code; ENS support-article new slug; retired Microsoft Defender support article → current page; Gnosis validators →validategnosis.com; grant and desktop-subdomain links → canonical URLs; "awesome list" → internal/docs/references/awesome-list.bee/releases/latest(always-latest redirect), valid Discord invites, and bot-blocked-but-live sites (gnosisscan, npmjs, gnu.org, readthedocs).fix(llms)): dropped a trailing slash on the DISC index entry (flagged stale); added Multi-Author Blog and Developer Resources entries.sidebars.js, unlinked, placeholder body) — removed.fix(scripts)):checkLlmsTxt()now skips@docusaurus/plugin-client-redirectsmeta-refresh stubs, cuttingllms.txt"missing pages" noise from 26 → 4 (only intentional nav-landing intros remain).awesome-swarmlist are fixed upstream separately; Fair Data Society links (fairdrop 502, xdai RPC) held pending a team check.Checklist ✅
masterand resolved conflictsnpm run buildsucceedsnpm run check:links) where relevantstatic/llms.txtupdated if pages were added / renamed / deletedSwarmvsswarm, ..)git commit -s)🤖 Generated with Claude Code