From 799e70b45efdbf48aa16b5d597410ba2604e9f30 Mon Sep 17 00:00:00 2001 From: Yejin Kelly Joo Date: Thu, 9 Jul 2026 15:05:09 +0900 Subject: [PATCH 1/4] docs: remove orphaned verify.md placeholder page - 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) Signed-off-by: Yejin Kelly Joo --- docs/bee/installation/verify.md | 6 ------ 1 file changed, 6 deletions(-) delete mode 100644 docs/bee/installation/verify.md diff --git a/docs/bee/installation/verify.md b/docs/bee/installation/verify.md deleted file mode 100644 index 1cab932c8..000000000 --- a/docs/bee/installation/verify.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: Reference documentation for node verification procedures. ---- -verify.md - -https://github.com/ethersphere/bee/pull/1581 From 55b5ff65e4313984e460a82081ff25ba8ab7ce65 Mon Sep 17 00:00:00 2001 From: Yejin Kelly Joo Date: Thu, 9 Jul 2026 15:05:23 +0900 Subject: [PATCH 2/4] fix(docs): update stale and broken external links - 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) Signed-off-by: Yejin Kelly Joo --- docs/bee/installation/build-from-source.md | 4 ++-- docs/bee/installation/connectivity.md | 2 +- docs/bee/installation/getting-started.md | 2 +- docs/bee/installation/package-manager.md | 2 +- docs/bee/installation/shell-script.md | 2 +- docs/bee/working-with-bee/bee-api.md | 2 +- docs/develop/host-your-website.md | 4 ++-- docs/develop/resources-md.md | 15 +++++++-------- .../develop/tools-and-features/ai-agent-skills.md | 4 ++-- .../tools-and-features/starting-a-test-network.md | 2 +- docs/references/community.md | 4 ++-- docs/references/glossary.md | 2 +- 12 files changed, 22 insertions(+), 23 deletions(-) diff --git a/docs/bee/installation/build-from-source.md b/docs/bee/installation/build-from-source.md index 182807f09..7bcf232ab 100644 --- a/docs/bee/installation/build-from-source.md +++ b/docs/bee/installation/build-from-source.md @@ -4,13 +4,13 @@ id: build-from-source description: Guides developers through compiling Bee directly from source code using Go git and make with step-by-step instructions. --- -Bee is written using the [Go](https://golang.org) language. +Bee is written using the [Go](https://go.dev) language. You may build the Bee client software directly from the [source](https://github.com/ethersphere/bee). Prerequisites for installing directly from source are: -- **go** - download the latest release from [golang.org](https://golang.org/dl). +- **go** - download the latest release from [go.dev](https://go.dev/dl). - **git** - download from [git-scm.com](https://git-scm.com/). - **make** - [make](https://www.gnu.org/software/make/) is usually included by default in most UNIX operating systems, and can be installed and used on almost any other operating system where it is not included by default. diff --git a/docs/bee/installation/connectivity.md b/docs/bee/installation/connectivity.md index 5b5afc6d7..0a56ced3b 100644 --- a/docs/bee/installation/connectivity.md +++ b/docs/bee/installation/connectivity.md @@ -418,7 +418,7 @@ using the local IP `nc -zv 192.168.0.10 1634`. Ubuntu uses [UFW](https://help.ubuntu.com/community/UFW), MacOS can be configured using the _Firewall_ tab in the _Security & Privacy_ section of _System Preferences_. Windows uses -[Defender Firewall](https://support.microsoft.com/en-us/help/4028544/windows-10-turn-microsoft-defender-firewall-on-or-off). +[Defender Firewall](https://support.microsoft.com/en-US/windows/security/windows-security/firewall-and-network-protection-in-the-windows-security-app). For each of these firewalls, set a special rule to allow UDP and TCP traffic to pass through on port `1634`. You may want to limit this diff --git a/docs/bee/installation/getting-started.md b/docs/bee/installation/getting-started.md index 38e7f3224..dba2f5a60 100644 --- a/docs/bee/installation/getting-started.md +++ b/docs/bee/installation/getting-started.md @@ -52,7 +52,7 @@ Refer to the [Node Types](./../working-with-bee/node-types.md) page for deep div While not strictly required, these tools will *greatly* simplify your experience working with Bee nodes: -- **[`jq`](https://jqlang.github.io/jq/)**: Formats JSON responses (recommended for API users). +- **[`jq`](https://jqlang.org/)**: Formats JSON responses (recommended for API users). - **[`curl`](https://curl.se/)**: Used for sending API requests (required for API interactions). - **[Swarm CLI](./../working-with-bee/swarm-cli.md)**: Terminal-based Bee node management. - **[Bee JS](./../../develop/tools-and-features/bee-js.md)**: JavaScript library for programmatic API access. diff --git a/docs/bee/installation/package-manager.md b/docs/bee/installation/package-manager.md index 9b9ac07c1..a79a322c9 100644 --- a/docs/bee/installation/package-manager.md +++ b/docs/bee/installation/package-manager.md @@ -427,7 +427,7 @@ Success! The Bee API is now listening! Next, let's see if we have connected with any peers by sending a query to the Bee API (port 1633 by default - `localhost:1633`). :::info -Here we are using the `jq` [utility](https://jqlang.github.io/jq/) to parse our javascript. Use your package manager to install `jq`, or simply remove everything after and including the first `|` to view the raw json without it. +Here we are using the `jq` [utility](https://jqlang.org/) to parse our javascript. Use your package manager to install `jq`, or simply remove everything after and including the first `|` to view the raw json without it. ::: ```bash diff --git a/docs/bee/installation/shell-script.md b/docs/bee/installation/shell-script.md index 4ac75723f..fb7f70489 100644 --- a/docs/bee/installation/shell-script.md +++ b/docs/bee/installation/shell-script.md @@ -453,7 +453,7 @@ This process can take a while, even up to several hours depending on your system You check your node's progress with the `/status` endpoint: :::info -The [`jq` utility](https://jqlang.github.io/jq/) jq utility formats API responses for easier reading: +The [`jq` utility](https://jqlang.org/) jq utility formats API responses for easier reading: * Install it using your system’s package manager. * If you don't want to use it, remove `| jq` from all commands. ::: diff --git a/docs/bee/working-with-bee/bee-api.md b/docs/bee/working-with-bee/bee-api.md index b06a12daa..ccb503fb1 100644 --- a/docs/bee/working-with-bee/bee-api.md +++ b/docs/bee/working-with-bee/bee-api.md @@ -43,7 +43,7 @@ curl -s http://localhost:1633/peers | jq '.peers | length' Great! We can see that we are currently connected with 23 other nodes! :::info -Here we are using the `jq` command line utility to count the amount of objects in the `peers` array in the JSON response we have received from our API, learn more about how to install and use `jq` [here](https://jqlang.github.io/jq/). +Here we are using the `jq` command line utility to count the amount of objects in the `peers` array in the JSON response we have received from our API, learn more about how to install and use `jq` [here](https://jqlang.org/). ::: Let's review a handful of endpoints which will provide you with important information relevant to detecting and diagnosing problems with your nodes. diff --git a/docs/develop/host-your-website.md b/docs/develop/host-your-website.md index c51eace62..556ecb6c9 100644 --- a/docs/develop/host-your-website.md +++ b/docs/develop/host-your-website.md @@ -143,7 +143,7 @@ Website Swarm Hash: 6c45eae389b3bffce21443316d0bd47c4101545092b7c72c313a33ee7d00 Feed Manifest: caa414d70028d14b0bdd9cbab18d1c1a0a3bab1b20a56cf06937a6b20c7e7377 ``` -Follow the [official ENS guide](https://support.ens.domains/en/articles/12275979-how-to-add-a-decentralized-website-to-an-ens-name) for registering a content hash adding your content hash in the ENS UI (see [guide](#optional-connect-site-to-ens-domain)). However, rather than registering your website's hash directly, register the feed manifest hash we saved from the previous step from our example above. +Follow the [official ENS guide](https://support.ens.domains/en/articles/12275979-how-do-i-add-a-decentralised-website-to-my-ens-name) for registering a content hash adding your content hash in the ENS UI (see [guide](#optional-connect-site-to-ens-domain)). However, rather than registering your website's hash directly, register the feed manifest hash we saved from the previous step from our example above. ``` bzz:// @@ -178,7 +178,7 @@ http://localhost:1633/bzz/yourname.eth/ ENS provides a clear walkthrough with screenshots showing how to add a content hash to your domain with their [easy to use app](https://app.ens.domains/): -[How to add a Decentralized website to an ENS name](https://support.ens.domains/en/articles/12275979-how-to-add-a-decentralized-website-to-an-ens-name) +[How to add a Decentralized website to an ENS name](https://support.ens.domains/en/articles/12275979-how-do-i-add-a-decentralised-website-to-my-ens-name) The guide covers: diff --git a/docs/develop/resources-md.md b/docs/develop/resources-md.md index 26bfdd95e..49381cf53 100644 --- a/docs/develop/resources-md.md +++ b/docs/develop/resources-md.md @@ -52,11 +52,10 @@ description: A curated list of Swarm developer resources — docs, SDKs, example - [Cafe137/etherjot ↗](https://github.com/Cafe137/etherjot) — Static blog generator, live at etherjot.eth.limo - [ethersphere/examples ↗](https://github.com/ethersphere/examples) — Collection of example apps and starters -- [examples/simple-blog ↗](https://github.com/ethersphere/examples/tree/master/simple-blog) — Minimal feed-backed blog, one publisher, updatable content -- [examples/multi-author-blog ↗](https://github.com/ethersphere/examples/tree/master/multi-author-blog) — Multi-author blog using per-author feeds and a shared index -- [examples/website ↗](https://github.com/ethersphere/examples/tree/master/website) — Swarm + ENS starter, upload a site and resolve it via ENS -- [examples/routing-manifest ↗](https://github.com/ethersphere/examples/tree/master/routing-manifest) — Manifest-based routing demo for single-page apps -- [examples/basic-static-website ↗](https://github.com/ethersphere/examples/tree/main/basic-static-website) — Basic static website on Swarm +- [examples/simple-blog ↗](https://github.com/ethersphere/examples/tree/main/simple-blog) — Minimal feed-backed blog, one publisher, updatable content +- [examples/multi-author-blog ↗](https://github.com/ethersphere/examples/tree/main/multi-author-blog) — Multi-author blog using per-author feeds and a shared index +- [examples/website ↗](https://github.com/ethersphere/examples/tree/main/website) — Upload a static website to Swarm, publish it to a feed for a stable URL, and resolve it via ENS +- [examples/routing-manifest ↗](https://github.com/ethersphere/examples/tree/main/routing-manifest) — Manifest-based routing demo for single-page apps ### Streaming @@ -101,8 +100,8 @@ description: A curated list of Swarm developer resources — docs, SDKs, example - [ethersphere/create-swarm-app ↗](https://github.com/ethersphere/create-swarm-app) — Boilerplate for building Swarm apps with JavaScript - [Cafe137/fdp-play ↗](https://github.com/Cafe137/fdp-play) — Docker-based local Bee cluster and FDP dev environment - [Cafe137/pss-gsoc-learning-material ↗](https://github.com/Cafe137/pss-gsoc-learning-material) — Learning material for PSS and GSOC primitives -- [examples/dynamic-content ↗](https://github.com/ethersphere/examples/tree/master/dynamic-content) — Content addressing and feeds, introduction example -- [examples/filesystem ↗](https://github.com/ethersphere/examples/tree/master/filesystem) — Filesystem-style operations using bee-js +- [examples/dynamic-content ↗](https://github.com/ethersphere/examples/tree/main/dynamic-content) — Content addressing and feeds, introduction example +- [examples/filesystem ↗](https://github.com/ethersphere/examples/tree/main/filesystem) — Filesystem-style operations using bee-js - [agazso/swarm-cid-converter ↗](https://github.com/agazso/swarm-cid-converter) — Convert Swarm hashes or links to CID and vice versa - [Solar-Punk-Ltd/ipfs-to-swarm ↗](https://github.com/Solar-Punk-Ltd/ipfs-to-swarm) — Migrate data from IPFS to Swarm @@ -120,7 +119,7 @@ description: A curated list of Swarm developer resources — docs, SDKs, example - [SwarmScan ↗](https://swarmscan.io/) — Network explorer and node statistics - [Swarm Gateway ↗](https://gateway.ethswarm.org/) — Share files via URL -- [Swarm Desktop ↗](https://desktop.ethswarm.org) — GUI node for non-technical users +- [Swarm Desktop ↗](https://ethswarm.org/build/desktop) — GUI node for non-technical users - [Bee Dashboard ↗](https://github.com/ethersphere/bee-dashboard) — Web UI for node management ## Community diff --git a/docs/develop/tools-and-features/ai-agent-skills.md b/docs/develop/tools-and-features/ai-agent-skills.md index 8e7ce48d9..fcc97f95a 100644 --- a/docs/develop/tools-and-features/ai-agent-skills.md +++ b/docs/develop/tools-and-features/ai-agent-skills.md @@ -6,7 +6,7 @@ description: Interactive Claude Code skills that guide you through setting up Be [Swarm Quickstart Skills](https://github.com/ethersphere/swarm-quickstart-skills) is a set of interactive guides ("skills") that run inside -[Claude Code](https://claude.com/claude-code). Instead of copying commands from +[Claude Code](https://claude.com/product/claude-code). Instead of copying commands from the docs by hand, the skills check your prerequisites first, run real commands against your Bee node, and explain what is happening at each step. Type `/swarm` and you are routed to the right next step for your current setup — installing a @@ -14,7 +14,7 @@ node, buying a postage stamp, uploading files, or scaffolding a dApp. ## Requirements -- [Claude Code](https://claude.com/claude-code) +- [Claude Code](https://claude.com/product/claude-code) - Node.js 18+ - A running Bee light node at `http://localhost:1633` (for most skills) - The diff --git a/docs/develop/tools-and-features/starting-a-test-network.md b/docs/develop/tools-and-features/starting-a-test-network.md index 56e1a6c37..3980f2dbd 100644 --- a/docs/develop/tools-and-features/starting-a-test-network.md +++ b/docs/develop/tools-and-features/starting-a-test-network.md @@ -92,7 +92,7 @@ curl -s http://localhost:1733/topology | jq .connected No connections yet? Right! Let's remedy that! :::info -Here we are using the `jq` command line utility to count the amount of objects in the `peers` array in the JSON response we have received from our API, learn more about how to install and use `jq` [here](https://jqlang.github.io/jq/). +Here we are using the `jq` command line utility to count the amount of objects in the `peers` array in the JSON response we have received from our API, learn more about how to install and use `jq` [here](https://jqlang.org/). ::: ### Making a network diff --git a/docs/references/community.md b/docs/references/community.md index 1512c5ba4..335821ef6 100644 --- a/docs/references/community.md +++ b/docs/references/community.md @@ -16,7 +16,7 @@ description: Information about Swarm community channels resources and contributi ## Awesome Swarm -An [awesome list](https://awesome.re) on anything awesome related to the Swarm platform. 🐝 🐝 🐝 +An [awesome list](/docs/references/awesome-list) on anything awesome related to the Swarm platform. 🐝 🐝 🐝 To see the most up to date list or submit an addition to it, make sure to check the [awesome-swarm repo](https://github.com/ethersphere/awesome-swarm). @@ -24,7 +24,7 @@ To see the most up to date list or submit an addition to it, make sure to check Swarm grants support many interesting projects that are already building their products on top of Swarm. Swarm bounties extend the ecosystem with tooling and infrastructure. -If you have an idea for a project which uses Swarm's technology we welcome you to [apply for a grant](https://grants.ethswarm.org). +If you have an idea for a project which uses Swarm's technology we welcome you to [apply for a grant](https://www.ethswarm.org/grants/swarm-grants-programme). Learn more about grants for building on Swarm at the [EthSwarm homepage](https://www.ethswarm.org/grants). diff --git a/docs/references/glossary.md b/docs/references/glossary.md index bc4814743..3b03d8597 100644 --- a/docs/references/glossary.md +++ b/docs/references/glossary.md @@ -13,7 +13,7 @@ Swarm is also the name of the core organization that oversees the development an ## Gnosis Chain -[Gnosis Chain](https://www.gnosis.io/) (previously known as xDai chain) is a [PoS](https://www.gnosis.io/validators), [EVM](https://ethereum.org/developers/docs/evm/) compatible Ethereum [sidechain](https://ethereum.org/developers/docs/scaling/sidechains/) which uses the same addressing scheme as Ethereum. Swarm's smart contracts have been issued on Gnosis Chain. +[Gnosis Chain](https://www.gnosis.io/) (previously known as xDai chain) is a [PoS](https://www.validategnosis.com/), [EVM](https://ethereum.org/developers/docs/evm/) compatible Ethereum [sidechain](https://ethereum.org/developers/docs/scaling/sidechains/) which uses the same addressing scheme as Ethereum. Swarm's smart contracts have been issued on Gnosis Chain. ## Smart Contracts From b66d3de9f3036eaf7c55d2bd1cba1a51454ff90a Mon Sep 17 00:00:00 2001 From: Yejin Kelly Joo Date: Thu, 9 Jul 2026 15:05:32 +0900 Subject: [PATCH 3/4] fix(llms): correct stale entry and add missing content pages - 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) Signed-off-by: Yejin Kelly Joo --- static/llms.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/static/llms.txt b/static/llms.txt index 5da429ede..c4e44db59 100644 --- a/static/llms.txt +++ b/static/llms.txt @@ -57,6 +57,7 @@ This is the documentation for [Swarm](https://www.ethswarm.org/) and its referen - [Host a Webpage](https://docs.ethswarm.org/docs/develop/host-your-website): Upload and serve static websites on Swarm - [Website Routing](https://docs.ethswarm.org/docs/develop/routing): Custom domains, ENS resolution, and routing configuration - [Run a Gateway](https://docs.ethswarm.org/docs/develop/gateway-proxy): Serve Swarm content over HTTP to regular browsers +- [Multi-Author Blog](https://docs.ethswarm.org/docs/develop/multi-author-blog): Build a multi-author blog on Swarm using per-author feeds and a shared index ## Build applications on Swarm @@ -73,11 +74,12 @@ This is the documentation for [Swarm](https://www.ethswarm.org/) and its referen - [Starting a Private Network](https://docs.ethswarm.org/docs/develop/tools-and-features/starting-a-test-network): Multi-node test clusters - [Dynamic Content](https://docs.ethswarm.org/docs/develop/dynamic-content): Updatable content using feeds - [Ultra Light Nodes](https://docs.ethswarm.org/docs/develop/ultra-light-nodes): Minimal nodes for lightweight client use cases +- [Developer Resources](https://docs.ethswarm.org/docs/develop/resources): Curated SDKs, libraries, example apps, and community tools for building on Swarm ## Understand Swarm concepts - [What is Swarm?](https://docs.ethswarm.org/docs/concepts/what-is-swarm): Architecture overview and design goals -- [DISC](https://docs.ethswarm.org/docs/concepts/DISC/): Distributed Immutable Store for Chunks +- [DISC](https://docs.ethswarm.org/docs/concepts/DISC): Distributed Immutable Store for Chunks - [Kademlia](https://docs.ethswarm.org/docs/concepts/DISC/kademlia): Distributed hash table and routing - [Neighborhoods](https://docs.ethswarm.org/docs/concepts/DISC/neighborhoods): Address space, proximity, and storage responsibility - [Erasure Coding (theory)](https://docs.ethswarm.org/docs/concepts/DISC/erasure-coding): Reed-Solomon redundancy for chunk reliability From 283b959cde9b73d49a89987d31f14740a6ed96ea Mon Sep 17 00:00:00 2001 From: Yejin Kelly Joo Date: Thu, 9 Jul 2026 15:10:47 +0900 Subject: [PATCH 4/4] fix(scripts): skip redirect-stub pages in llms.txt coverage check - 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 Signed-off-by: Yejin Kelly Joo --- scripts/check_links.ts | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/scripts/check_links.ts b/scripts/check_links.ts index e9da11701..c70ee9453 100644 --- a/scripts/check_links.ts +++ b/scripts/check_links.ts @@ -658,6 +658,11 @@ function checkLlmsTxt(): LlmsTxtResult | null { if (!rel.startsWith('docs/')) continue; const docPath = rel.slice('docs/'.length); if (!docPath || docPath.startsWith('api/')) continue; + // Skip client-redirect stub pages (generated by @docusaurus/plugin-client-redirects): + // these are meta-refresh forwards from old URLs to their canonical target, not real + // content pages, so they must not count as "missing from llms.txt". + const html = fs.readFileSync(htmlFile, 'utf8'); + if (/]+http-equiv=["']refresh["']/i.test(html)) continue; buildPaths.add(docPath); }