prebuild script to eliminate client side fetching

Author: NoahMaizels

docs/references/awesome-list.mdx

@@ -1,10 +1,158 @@
 ---
 title: Awesome Swarm
-id: awesome-list
+sidebar_label: Awesome Swarm
+# Do NOT set 'id' here; we want the doc id to be 'references/awesome-list' from the path
 ---
 
-import AwesomeList from '@site/src/components/AwesomeList';
-
 *Contribute to the Awesome Swarm list on [GitHub](https://github.com/ethersphere/awesome-swarm).*
 
-<AwesomeList />
+[Swarm](https://www.ethswarm.org/) is an incentivized peer-to-peer storage and communication system. [Join the decentralized network with a Bee node](https://docs.ethswarm.org/docs/installation/quick-start), the basic building block of Swarm.
+
+This is a list of free and open source projects related to Swarm and its growing ecosystem.
+
+See [CONTRIBUTING.md](https://github.com/ethersphere/awesome-swarm/blob/master/CONTRIBUTING.md) to learn how to create your submission.
+
+## Table of contents
+
+Click on the menu icon next to [README.md](#readme) for a list of sections
+
+## Projects
+
+### Services
+
+**[`^ back to top ^`](#)**
+
+[Bee](https://github.com/ethersphere/bee) - Also referred to as the _node_ or the _client_, this service allows you to join the Swarm network
+
+
+### Libraries
+
+**[`^ back to top ^`](#)**
+
+[Bee-JS](https://github.com/ethersphere/bee-js) - A high-level Javascript library to interact with Bee through its REST API
+
+[Mantaray-js](https://github.com/ethersphere/mantaray-js) - A low-level Swarm manifest manipulation library
+
+[Mantaray-py](https://github.com/Ankvik-Tech-Labs/mantaray-py/) - Allows you to manipulate and interpret mantaray data via MantarayNode and MantarayFork abstractions.
+
+### CI/CD
+
+**[`^ back to top ^`](#)**
+
+[Beekeeper](https://github.com/ethersphere/beekeeper) - Orchestrate and test Bee clusters through Kubernetes
+
+[Swarm Actions](https://github.com/ethersphere/swarm-actions) - GitHub Actions workflow for uploading data to the Swarm network.  
+
+### UI
+
+**[`^ back to top ^`](#)**
+
+[Bee Dashboard](https://github.com/ethersphere/bee-dashboard) - React project to troubleshoot and interact with your Bee node
+
+[Gateway](https://github.com/ethersphere/gateway) - Gateway to the Swarm project, for uploading, downloading and sharing assets on the network
+
+[Swarmy](https://swarmy.cloud/) - Swarm as a service, makes it simple to store and retrieve data on Swarm. 
+
+[Swarm Desktop App](https://www.ethswarm.org/build/desktop) -  By running a lightweight Swarm node on your computer, you get direct access to the Swarm peer-to-peer network, without the need for centralized gateways.    
+
+[Etherjot](https://github.com/ethersphere/etherjot) - Bring your web3 blog live in minutes with Etherjot, a graphical blogging application natively supporting Swarm.
+
+[buzzMint](https://github.com/ethersphere/awesome-swarm/blob/master/buzz-mint.eth.limo) - A decentralised NFT creator.
+
+[Bchan](https://bchan.bzz.limo/) - A private message board allowing users to post images, text, and links across various threads.
+
+### Tools
+
+**[`^ back to top ^`](#)**
+
+[Swarm CLI](https://github.com/ethersphere/swarm-cli) - Do everything on Swarm with the power of the terminal
+
+[Swarm Extension](https://github.com/ethersphere/swarm-extension) - Official extension that adds Swarm support and injects Bee library to the browser
+
+[Swarm CID Converter](https://github.com/agazso/swarm-cid-converter) - Convert Swarm hashes or links to CID and vice versa.
+
+[Bee-AFS](https://github.com/aloknerurkar/bee-afs) - FUSE filesystem for Bee
+
+[Nextcloud Swarm Plugin](https://github.com/MetaProvide/nextcloud-swarm-plugin) - Plugin for bridging Nextcloud and Swarm.
+
+[Beest](https://github.com/w3rkspacelabs/beest) -  An interactive CLI toolkit that simplifies the management of multiple Bee nodes
+
+[Doctor Bee](https://github.com/w3rkspacelabs/doctor-bee) - A simple python script to check up a Bee node's health status.
+
+[IPFS to Swarm](https://github.com/Solar-Punk-Ltd/ipfs-to-swarm) - Migrate data from IPFS to Swarm.
+
+### Smart Contracts
+
+**[`^ back to top ^`](#)**
+
+[Swap, Swear and Swindle](https://github.com/ethersphere/swap-swear-and-swindle) - Protocols for peer-to-peer accounting
+
+[Storage Incentives](https://github.com/ethersphere/storage-incentives) - Smart contracts providing the basis for Swarm's storage incentivization model
+
+### Documentation
+
+**[`^ back to top ^`](#)**
+
+[The Book of Swarm](https://docs.ethswarm.org/the-book-of-swarm.pdf) - Storage and communication infrastructure for self-sovereign digital society back-end stack for the decentralised web
+
+[Bee Docs](https://github.com/ethersphere/bee-docs) - Documentation for the Swarm Bee Client. View at [docs.ethswarm.org](https://docs.ethswarm.org/docs/).
+
+[Bee-JS Docs](https://github.com/ethersphere/bee-js-docs) - Documentation for the Swarm Bee-js javascript library. View at [bee-js.ethswarm.org](https://bee-js.ethswarm.org/docs/).
+
+[Swarm Specification](https://papers.ethswarm.org/p/swarm-specification/) - The Swarm specification document is an essential resource for developers and software engineers seeking to build their own Swarm client or integrate Swarm's functionalities into their applications.
+
+[Swarm Erasure Coding paper](https://papers.ethswarm.org/p/erasure/) - The erasure coding paper provides a technical exploration of erasure coding in the Swarm network, focusing on ensuring data integrity and resilience.
+
+[Swarm Papers](https://papers.ethswarm.org/) - Swarm’s documentation includes a variety of papers from technical specifications to in-depth explorations of the network's architecture and functionalities.
+
+[Bee API Reference](https://docs.ethswarm.org/api/) - Bee API Documentation.
+
+
+### Community / Ecosystem
+
+**[`^ back to top ^`](#)**
+
+[Fair data society](https://fairdatasociety.org/) - Ecosystem initiative for ethical Web3
+
+[FairOS](https://github.com/fairDataSociety/fairOS-dfs) - Distributed file system, key-value store and nosql store on Swarm (for developers)
+
+[The Fair Data Protocol (FDP)](https://fdp.fairdatasociety.org/) - A data interoperability protocol for dApps that use personal data.
+ 
+[FDP play](https://github.com/fairDataSociety/fdp-play) - CLI tool to spin up local development FDP environment and Bee cluster with Docker
+
+[Fairdrive](https://fairdrive.fairdatasociety.org/) - Decentralised and unstoppable "Dropbox" for end-users and developers using Fair Data Protocol
+
+[Fairdrive code](https://github.com/fairDataSociety/fairdrive-theapp) - Code for decentralised and unstoppable "Dropbox" for end-users and developers using Fair Data Protocol
+
+[Galileo](https://app.galileo.fairdatasociety.org/) - Open Street Maps on Swarm
+
+[SwarmScan](https://swarmscan.resenje.org/) - Get network insights
+
+[Etherna.io](https://etherna.io/) - Decentralised media platform on Swarm
+
+[SwarmNFT library](https://github.com/igar1991/SwarmNFT) - JavaScript library for creating NFTs on Ethereum-compatible blockchains and storing content on Swarm
+
+[videoNFT](https://github.com/pabloVoorvaart/videoNFT/) - NFT live streaming with Swarm (winner of EthBerlin3 2022 Freedom to Transact Track)
+
+[DeBoot](https://github.com/awmacpherson/deboot) - DeBoot is a project to research and implement approaches to bootloading OS images from a decentralized storage network such as Swarm or IPFS.
+
+[Swarm DAppNode Package](https://github.com/rndlabs/dappnodepackage-swarm) - Swarm DAppNode package for Swarm Mainnet with multi-platform (x86_64 and arm64) support. Testnet DAppNode packages can be found [here](https://github.com/rndlabs/dappnodepackage-swarm-testnet).
+
+[Mipasa Swarm Connector](https://github.com/MiPasa/mipasa-swarm-connector/) - MiPasa connector for Swarm (BZZ) distributed storage network.
+
+[Export Webpage on Swarm](https://github.com/ethersphere/devcon-swarm-exporter) - CLI tool to build an optimized static export of devcon app frontend.
+
+[Blob Storage on Swarm](https://github.com/Blobscan/blobscan) - The pioneer blockchain explorer dedicated to navigate and visualize shard blob transactions.
+
+[SWIPs](https://github.com/ethersphere/SWIPs) - The Swarm Improvement Proposal repository.
+
+### Miscellaneous
+
+**[`^ back to top ^`](#)**
+
+[Swarm Bot](https://github.com/ethersphere/swarm-bot) - Discord bot handling commands related to Swarm and its community
+
+[ethersphere/bee DeepWiki](https://deepwiki.com/ethersphere/bee) - The DeepWiki for the Bee client GitHub repository. DeepWiki is a tool which provides autogenerated documentation (using LLM ai agents such as ChatGPT or Google Gemini) based directly on code from a GitHub repository. It also has a question box where any question can be asked about the Bee codebase.
+
+
+*As with all LLMs, DeepWiki may sometimes be confidently wrong. Make sure to always double check (either by inspecting the code yourself, or confirming with a Bee team core developer) before assuming its answers are correct.*

scripts/fetch-awesome-swarm.mjs

@@ -1,50 +1,57 @@
+// Fetch Awesome Swarm README and emit a doc under docs/references.
+// Result: docs/references/awesome-list.mdx (visible to Docs plugin + sidebars)
+
 import { mkdir, writeFile } from 'node:fs/promises';
 import { resolve, dirname } from 'node:path';
 
 const SOURCE_URL =
   'https://raw.githubusercontent.com/ethersphere/awesome-swarm/refs/heads/master/README.md';
 
-// We will generate the actual page file (single route, no imports)
-const OUT_PATH = resolve(process.cwd(), 'src/pages/awesome-swarm.mdx');
+const OUT_PATH = resolve(process.cwd(), 'docs/references/awesome-list.mdx');
+
+const REPO_HTTP_BASE = 'https://github.com/ethersphere/awesome-swarm/blob/master/';
+const RAW_HTTP_BASE  = 'https://raw.githubusercontent.com/ethersphere/awesome-swarm/master/';
 
-// Matches the line like: [.. DeepWiki ..](...) - ...
-const deepWikiLine = /^\[[^\]]*DeepWiki[^\]]*\]\([^)]+\)\s*-\s*.*$/im;
+function normalizeNewlines(str) {
+  return str.replace(/\r\n/g, '\n');
+}
+
+function rewriteRelativeLinks(md) {
+  // Images: ![alt](path) where path is relative
+  md = md.replace(
+    /!\[([^\]]*)\]\((?!https?:|#|mailto:)([^)]+)\)/g,
+    (_m, alt, path) => `![${alt}](${RAW_HTTP_BASE}${path})`
+  );
+  // Links: [text](path) where path is relative
+  md = md.replace(
+    /\[([^\]]+)\]\((?!https?:|#|mailto:)([^)]+)\)/g,
+    (_m, text, path) => `[${text}](${REPO_HTTP_BASE}${path})`
+  );
+  return md;
+}
 
 async function main() {
   const res = await fetch(SOURCE_URL);
   if (!res.ok) throw new Error(`Fetch failed: ${res.status} ${res.statusText}`);
 
-  let md = (await res.text()).replace(/\r\n/g, '\n');
+  let md = normalizeNewlines(await res.text());
 
-  // Optionally strip upstream H1 to avoid duplicate title
-  // md = md.replace(/^# .*\n+/, '');
+  // Optional: strip upstream H1 to avoid a second big title under our frontmatter title
+  md = md.replace(/^# .*\n+/, '');
+
+  md = rewriteRelativeLinks(md);
 
-  // Build the full MDX page. We’ll inject the JSX admonition after the DeepWiki entry if found.
   const header = `---
 title: Awesome Swarm
-id: awesome-list
+sidebar_label: Awesome Swarm
+# Do NOT set 'id' here; we want the doc id to be 'references/awesome-list' from the path
 ---
 
 *Contribute to the Awesome Swarm list on [GitHub](https://github.com/ethersphere/awesome-swarm).*
 
-import Admonition from '@theme/Admonition';
-`;
-
-  const admonition = `
-<Admonition type="caution">
-As with all LLMs, DeepWiki may sometimes be confidently wrong. Make sure to always double check (either by inspecting the code yourself, or confirming with a Bee team core developer) before assuming its answers are correct.
-</Admonition>
 `;
 
-  let body;
-  if (deepWikiLine.test(md)) {
-    body = md.replace(deepWikiLine, (match) => `${match}\n\n${admonition}`);
-  } else {
-    // Fallback: put admonition near top (after the header)
-    body = `${admonition}\n${md}`;
-  }
-
-  const page = `${header}\n${body}\n`;
+  const page = `${header}${md}\n`;
 
   await mkdir(dirname(OUT_PATH), { recursive: true });
   await writeFile(OUT_PATH, page, 'utf8');