From 7c81c423abd98d74833de89d0af050220bd6e5a0 Mon Sep 17 00:00:00 2001
From: Yejin Kelly Joo <yejinkellyjoo@gmail.com>
Date: Thu, 16 Jul 2026 16:40:27 +0900
Subject: [PATCH 1/5] feat(scripts): mirror swarm-cheatsheets into static at
 build time

- add scripts/fetch-cheatsheets.mjs to fetch the cheatsheet page, assets, and PDF from swarm-cheatsheets@main and mirror them into static/cheatsheets/ with asset paths rewritten
- fetch files concurrently with a per-request timeout, prune the output dir first, and fail the build on any fetch error
- wire the script into the prebuild chain and gitignore the generated static/cheatsheets output

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Yejin Kelly Joo <yejinkellyjoo@gmail.com>
---
 .gitignore                    |   1 +
 package.json                  |   2 +-
 scripts/fetch-cheatsheets.mjs | 101 ++++++++++++++++++++++++++++++++++
 3 files changed, 103 insertions(+), 1 deletion(-)
 create mode 100644 scripts/fetch-cheatsheets.mjs

diff --git a/.gitignore b/.gitignore
index 62066d1d6..942a52497 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,6 +9,7 @@ resources
 .netlify
 /src/pages/awesome-swarm.mdx
 /static/openapi.yaml
+/static/cheatsheets
 test
 docs/references/awesome-list.mdx
 *.zip
diff --git a/package.json b/package.json
index 70f7a42f2..8379aaff9 100644
--- a/package.json
+++ b/package.json
@@ -5,7 +5,7 @@
   "scripts": {
     "docusaurus": "docusaurus",
     "start": "docusaurus start",
-    "prebuild": "node -e \"require('fs').copyFileSync('openapi/Swarm.yaml', 'static/openapi.yaml')\" && node scripts/fetch-awesome-swarm.mjs && node scripts/validate-llms-txt.mjs",
+    "prebuild": "node -e \"require('fs').copyFileSync('openapi/Swarm.yaml', 'static/openapi.yaml')\" && node scripts/fetch-awesome-swarm.mjs && node scripts/fetch-cheatsheets.mjs && node scripts/validate-llms-txt.mjs",
     "build": "docusaurus build",
     "build:quiet": "cross-env NODE_OPTIONS=\"--disable-warning=DEP0040 --disable-warning=DEP0169\" docusaurus build",
     "swizzle": "docusaurus swizzle",
diff --git a/scripts/fetch-cheatsheets.mjs b/scripts/fetch-cheatsheets.mjs
new file mode 100644
index 000000000..08787e46d
--- /dev/null
+++ b/scripts/fetch-cheatsheets.mjs
@@ -0,0 +1,101 @@
+// Mirror the Swarm cheatsheet(s) from the swarm-cheatsheets repo into static/,
+// so they are served from our own domain (docs.ethswarm.org/cheatsheets/…) and
+// embedded in a doc page via <iframe>. The swarm-cheatsheets repo stays the
+// single source of truth; this fetches a fresh copy on every build.
+//
+// Layout served (mirrors the repo's own scripts/site.sh, but with a shared
+// asset dir one level up so cheatsheets don't each duplicate the fonts):
+//   static/cheatsheets/<topic>/index.html   ← page (asset paths rewritten)
+//   static/cheatsheets/assets/…             ← fonts, vendor QR lib, logos
+//   static/cheatsheets/<name>.pdf           ← Download-button target
+
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+
+const RAW_BASE =
+  'https://raw.githubusercontent.com/ethersphere/swarm-cheatsheets/main/';
+
+const OUT_DIR = resolve(process.cwd(), 'static/cheatsheets');
+
+// Bound each fetch so a stalled CDN connection can't hang the build forever.
+const FETCH_TIMEOUT_MS = 20000;
+
+// Shared, binary-safe assets — copied verbatim. Paths are relative to OUT_DIR
+// and must match what the rewritten pages point at.
+const ASSETS = [
+  'assets/favicon.png',
+  'assets/swarm-logo.svg',
+  'assets/swarm-logo-white.svg',
+  'assets/vendor/qrcode.min.js',
+  'assets/fonts/fonts.css',
+  'assets/fonts/dm-mono-400-latin.woff2',
+  'assets/fonts/dm-mono-500-latin.woff2',
+  'assets/fonts/dm-sans-400-latin.woff2',
+  'assets/fonts/dm-sans-500-latin.woff2',
+  'assets/fonts/dm-sans-700-latin.woff2',
+  'assets/fonts/space-grotesk-500-latin.woff2',
+  'assets/fonts/space-grotesk-600-latin.woff2',
+  'assets/fonts/space-grotesk-700-latin.woff2',
+];
+
+function rewriteAssetPaths(html) {
+  // Match the repo's site.sh rewrite, adapted to the shared asset dir:
+  //   ../../../assets/  → ../assets/   (→ /cheatsheets/assets/…)
+  //   ../../../dist/    → ../          (→ /cheatsheets/<name>.pdf)
+  return html
+    .replace(/\.\.\/\.\.\/\.\.\/assets\//g, '../assets/')
+    .replace(/\.\.\/\.\.\/\.\.\/dist\//g, '../');
+}
+
+async function fetchOrThrow(url) {
+  const res = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+  if (!res.ok) throw new Error(`Fetch failed: ${res.status} ${res.statusText} — ${url}`);
+  return res;
+}
+
+async function writeOut(relPath, data) {
+  const out = resolve(OUT_DIR, relPath);
+  await writeFile(out, data);
+  console.log(`Wrote ${out}`);
+}
+
+// Everything to mirror, as {src, dest, transform?}. `transform` (text pages
+// only) rewrites asset paths; without it the file is copied verbatim
+// (binary-safe). Adding a future cheatsheet is a one-line addition here.
+const FILES = [
+  { src: 'src/cheatsheets/overview/index.html', dest: 'overview/index.html', transform: rewriteAssetPaths },
+  ...ASSETS.map((rel) => ({ src: rel, dest: rel })),
+  { src: 'dist/swarm-overview-cheatsheet.pdf', dest: 'swarm-overview-cheatsheet.pdf' },
+];
+
+async function mirror({ src, dest, transform }) {
+  const res = await fetchOrThrow(RAW_BASE + src);
+  const data = transform ? transform(await res.text()) : Buffer.from(await res.arrayBuffer());
+  await writeOut(dest, data);
+}
+
+async function main() {
+  // Start clean so files dropped from the manifest (or renamed upstream) don't
+  // linger and get served — mirrors the source repo's site.sh `rm -rf $OUT`.
+  await rm(OUT_DIR, { recursive: true, force: true });
+
+  // Pre-create the unique target dirs once (sequentially, so nested dirs don't
+  // race on a shared ancestor), so the concurrent writes below never mkdir.
+  const dirs = new Set(FILES.map(({ dest }) => dirname(resolve(OUT_DIR, dest))));
+  for (const dir of dirs) await mkdir(dir, { recursive: true });
+
+  // Fetch all files concurrently; fail the build if any one fails (matches
+  // fetch-awesome-swarm.mjs), but let every fetch finish first so all failures
+  // are reported, not just the first.
+  const results = await Promise.allSettled(FILES.map(mirror));
+  const failed = results.filter((r) => r.status === 'rejected');
+  if (failed.length) {
+    for (const { reason } of failed) console.error(reason);
+    process.exit(1);
+  }
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

From 315a4a86c5b710af65aa5e824e3d3f018b9172fc Mon Sep 17 00:00:00 2001
From: Yejin Kelly Joo <yejinkellyjoo@gmail.com>
Date: Thu, 16 Jul 2026 16:40:34 +0900
Subject: [PATCH 2/5] docs(develop): add Swarm Cheatsheet page embedding the
 mirrored card

- add tools-and-features/cheatsheets page that embeds the mirrored cheatsheet via iframe and register it in the sidebar
- add a Swarm Cheatsheet card to the Setup section of the Start Building page
- add an llms.txt pointer to the self-hosted cheatsheet for agents

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Yejin Kelly Joo <yejinkellyjoo@gmail.com>
---
 docs/develop/introduction.md                  |  9 +++++++++
 .../develop/tools-and-features/cheatsheets.md | 19 +++++++++++++++++++
 sidebars.js                                   |  1 +
 static/llms.txt                               |  1 +
 4 files changed, 30 insertions(+)
 create mode 100644 docs/develop/tools-and-features/cheatsheets.md

diff --git a/docs/develop/introduction.md b/docs/develop/introduction.md
index edfcfe1be..49073bd91 100644
--- a/docs/develop/introduction.md
+++ b/docs/develop/introduction.md
@@ -44,6 +44,15 @@ This is the go-to starting point for web3 developers who want to build with Swar
           <span class="hub-card__cta">Start with AI</span>
         </a>
       </li>
+      <li class="hub-card">
+        <a class="hub-card__link" href="/docs/develop/tools-and-features/cheatsheets">
+          <h3 class="hub-card__title">Swarm Cheatsheet</h3>
+          <p class="hub-card__desc">
+            A dense, printable quick-reference for building on Swarm — what it is, its limits, and curated links to get started fast.
+          </p>
+          <span class="hub-card__cta">View cheatsheet</span>
+        </a>
+      </li>
     </ul>
   </div>
 
diff --git a/docs/develop/tools-and-features/cheatsheets.md b/docs/develop/tools-and-features/cheatsheets.md
new file mode 100644
index 000000000..4235f5443
--- /dev/null
+++ b/docs/develop/tools-and-features/cheatsheets.md
@@ -0,0 +1,19 @@
+---
+title: Swarm Cheatsheet
+id: cheatsheets
+description: A dense printable quick-reference for building on Swarm — what it is, its limits, and curated links to get started.
+hide_table_of_contents: true
+---
+
+The Swarm Cheatsheet is a dense, two-page quick-reference for building on Swarm.
+
+It's designed to print cleanly to A4, so you can keep it beside you at a hackathon or on your desk — use the **Download PDF** button on the card below to grab a copy.
+
+<iframe
+  src="/cheatsheets/overview/"
+  title="Swarm Cheatsheet"
+  loading="lazy"
+  style={{ width: '100%', height: '85vh', border: 0 }}
+></iframe>
+
+<a className="button button--primary button--lg" href="/cheatsheets/overview/" target="_blank" rel="noopener">Open the cheatsheet in a new tab</a>
diff --git a/sidebars.js b/sidebars.js
index f2eba68d4..9d5e29817 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -107,6 +107,7 @@ module.exports = {
       items: [
         'develop/tools-and-features/introduction',
         'develop/tools-and-features/ai-agent-skills',
+        'develop/tools-and-features/cheatsheets',
         'develop/tools-and-features/buy-a-stamp-batch',
         'develop/tools-and-features/bee-js',
         'develop/tools-and-features/gateway-proxy',
diff --git a/static/llms.txt b/static/llms.txt
index c4e44db59..96760dcc4 100644
--- a/static/llms.txt
+++ b/static/llms.txt
@@ -63,6 +63,7 @@ This is the documentation for [Swarm](https://www.ethswarm.org/) and its referen
 
 - [Bee JS](https://docs.ethswarm.org/docs/develop/tools-and-features/bee-js): JavaScript/TypeScript SDK for Swarm
 - [AI Agent Skills](https://docs.ethswarm.org/docs/develop/tools-and-features/ai-agent-skills): Claude Code skills that guide Swarm setup and building
+- [Swarm Cheatsheet](https://docs.ethswarm.org/cheatsheets/overview/): Printable quick-reference — what Swarm is/isn't, limitations, quickstart, and curated links for building on Swarm
 - [Chunk Types](https://docs.ethswarm.org/docs/develop/tools-and-features/chunk-types): Content-addressed chunks (CAC) and single-owner chunks (SOC)
 - [Feeds](https://docs.ethswarm.org/docs/develop/tools-and-features/feeds): Mutable data references using single-owner chunks
 - [Manifests](https://docs.ethswarm.org/docs/develop/tools-and-features/manifests): Trie-based path mapping for file collections

From d9eb1862dae69b9be2d3ff73086670952ad1834b Mon Sep 17 00:00:00 2001
From: Yejin Kelly Joo <yejinkellyjoo@gmail.com>
Date: Thu, 16 Jul 2026 18:29:16 +0900
Subject: [PATCH 3/5] fix(develop): auto-size the Swarm Cheatsheet iframe to
 its content

- grow the iframe to its content height on load so the page scrolls instead of the iframe
- re-measure with a ResizeObserver to track reflow after fonts load and QR codes render
- keep an 85vh min-height as a no-JS fallback

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Yejin Kelly Joo <yejinkellyjoo@gmail.com>
---
 docs/develop/tools-and-features/cheatsheets.md | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/docs/develop/tools-and-features/cheatsheets.md b/docs/develop/tools-and-features/cheatsheets.md
index 4235f5443..2573ffefc 100644
--- a/docs/develop/tools-and-features/cheatsheets.md
+++ b/docs/develop/tools-and-features/cheatsheets.md
@@ -13,7 +13,18 @@ It's designed to print cleanly to A4, so you can keep it beside you at a hackath
   src="/cheatsheets/overview/"
   title="Swarm Cheatsheet"
   loading="lazy"
-  style={{ width: '100%', height: '85vh', border: 0 }}
+  onLoad={(e) => {
+    // Same-origin (served from /cheatsheets/): grow the frame to its content
+    // height so the page scrolls, not the iframe. Re-measure on reflow (the
+    // card's fonts load and QR codes render after the initial load event).
+    const frame = e.currentTarget;
+    const doc = frame.contentDocument;
+    if (!doc) return;
+    const fit = () => { frame.style.height = doc.documentElement.scrollHeight + 'px'; };
+    fit();
+    new ResizeObserver(fit).observe(doc.documentElement);
+  }}
+  style={{ width: '100%', minHeight: '85vh', border: 0 }}
 ></iframe>
 
 <a className="button button--primary button--lg" href="/cheatsheets/overview/" target="_blank" rel="noopener">Open the cheatsheet in a new tab</a>

From 7cb1842193fb0bc440b652bf8f8feb450aba202c Mon Sep 17 00:00:00 2001
From: Yejin Kelly Joo <yejinkellyjoo@gmail.com>
Date: Thu, 16 Jul 2026 21:41:04 +0900
Subject: [PATCH 4/5] feat(develop): embed the card-only cheatsheet instead of
 the full page

- mirror cheatsheet.html (the A4 card) instead of index.html, dropping the source site's chrome, toolbar, and footer from the embed
- stop mirroring the chrome-only swarm-logo-white.svg
- replace the card's removed Download PDF button with Download PDF and open-in-new-tab links on the doc page

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Yejin Kelly Joo <yejinkellyjoo@gmail.com>
---
 docs/develop/tools-and-features/cheatsheets.md | 6 ++++--
 scripts/fetch-cheatsheets.mjs                  | 6 ++++--
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/docs/develop/tools-and-features/cheatsheets.md b/docs/develop/tools-and-features/cheatsheets.md
index 2573ffefc..88c06f9d9 100644
--- a/docs/develop/tools-and-features/cheatsheets.md
+++ b/docs/develop/tools-and-features/cheatsheets.md
@@ -7,7 +7,7 @@ hide_table_of_contents: true
 
 The Swarm Cheatsheet is a dense, two-page quick-reference for building on Swarm.
 
-It's designed to print cleanly to A4, so you can keep it beside you at a hackathon or on your desk — use the **Download PDF** button on the card below to grab a copy.
+It's designed to print cleanly to A4, so you can keep it beside you at a hackathon or on your desk — use the **Download PDF** link below to grab a copy.
 
 <iframe
   src="/cheatsheets/overview/"
@@ -27,4 +27,6 @@ It's designed to print cleanly to A4, so you can keep it beside you at a hackath
   style={{ width: '100%', minHeight: '85vh', border: 0 }}
 ></iframe>
 
-<a className="button button--primary button--lg" href="/cheatsheets/overview/" target="_blank" rel="noopener">Open the cheatsheet in a new tab</a>
+<a className="button button--primary button--lg" href="/cheatsheets/swarm-overview-cheatsheet.pdf" download>Download PDF</a>
+&nbsp;
+<a className="button button--secondary button--lg" href="/cheatsheets/overview/" target="_blank" rel="noopener">Open in a new tab</a>
diff --git a/scripts/fetch-cheatsheets.mjs b/scripts/fetch-cheatsheets.mjs
index 08787e46d..8d5f65e58 100644
--- a/scripts/fetch-cheatsheets.mjs
+++ b/scripts/fetch-cheatsheets.mjs
@@ -25,7 +25,6 @@ const FETCH_TIMEOUT_MS = 20000;
 const ASSETS = [
   'assets/favicon.png',
   'assets/swarm-logo.svg',
-  'assets/swarm-logo-white.svg',
   'assets/vendor/qrcode.min.js',
   'assets/fonts/fonts.css',
   'assets/fonts/dm-mono-400-latin.woff2',
@@ -63,8 +62,11 @@ async function writeOut(relPath, data) {
 // only) rewrites asset paths; without it the file is copied verbatim
 // (binary-safe). Adding a future cheatsheet is a one-line addition here.
 const FILES = [
-  { src: 'src/cheatsheets/overview/index.html', dest: 'overview/index.html', transform: rewriteAssetPaths },
+  // The card-only document (chrome/toolbar/footer live in the source's
+  // index.html and are intentionally excluded — we embed just the cheatsheet).
+  { src: 'src/cheatsheets/overview/cheatsheet.html', dest: 'overview/index.html', transform: rewriteAssetPaths },
   ...ASSETS.map((rel) => ({ src: rel, dest: rel })),
+  // Not referenced by the card; kept so the doc page can offer a download link.
   { src: 'dist/swarm-overview-cheatsheet.pdf', dest: 'swarm-overview-cheatsheet.pdf' },
 ];
 

From 00680ea51e82ea81f6bb439bf08161d01aa1d175 Mon Sep 17 00:00:00 2001
From: Yejin Kelly Joo <yejinkellyjoo@gmail.com>
Date: Thu, 16 Jul 2026 21:50:40 +0900
Subject: [PATCH 5/5] fix(develop): scale the embedded cheatsheet to the
 content width

- scale the fixed A4 card to fill the doc content column, removing the grey margins beside the centered sheet and enlarging it a bit
- size the wrapper to the scaled height so the page scrolls, refitting on reflow and window resize
- remove the redundant open-in-new-tab link

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Yejin Kelly Joo <yejinkellyjoo@gmail.com>
---
 .../develop/tools-and-features/cheatsheets.md | 52 ++++++++++++-------
 1 file changed, 33 insertions(+), 19 deletions(-)

diff --git a/docs/develop/tools-and-features/cheatsheets.md b/docs/develop/tools-and-features/cheatsheets.md
index 88c06f9d9..05edf6fac 100644
--- a/docs/develop/tools-and-features/cheatsheets.md
+++ b/docs/develop/tools-and-features/cheatsheets.md
@@ -9,24 +9,38 @@ The Swarm Cheatsheet is a dense, two-page quick-reference for building on Swarm.
 
 It's designed to print cleanly to A4, so you can keep it beside you at a hackathon or on your desk — use the **Download PDF** link below to grab a copy.
 
-<iframe
-  src="/cheatsheets/overview/"
-  title="Swarm Cheatsheet"
-  loading="lazy"
-  onLoad={(e) => {
-    // Same-origin (served from /cheatsheets/): grow the frame to its content
-    // height so the page scrolls, not the iframe. Re-measure on reflow (the
-    // card's fonts load and QR codes render after the initial load event).
-    const frame = e.currentTarget;
-    const doc = frame.contentDocument;
-    if (!doc) return;
-    const fit = () => { frame.style.height = doc.documentElement.scrollHeight + 'px'; };
-    fit();
-    new ResizeObserver(fit).observe(doc.documentElement);
-  }}
-  style={{ width: '100%', minHeight: '85vh', border: 0 }}
-></iframe>
+<div className="cheatsheet-embed" style={{ overflow: 'hidden', margin: '1.5rem -1rem' }}>
+  <iframe
+    src="/cheatsheets/overview/"
+    title="Swarm Cheatsheet"
+    loading="lazy"
+    onLoad={(e) => {
+      // Same-origin (served from /cheatsheets/): the card is a fixed 210mm A4
+      // sheet. Scale it to fill the wrapper — removes the grey margins beside
+      // the centered sheet and makes it a bit larger than native — then size
+      // the wrapper to the scaled height so the page (not the iframe) scrolls.
+      const frame = e.currentTarget;
+      const wrap = frame.parentElement;
+      const doc = frame.contentDocument;
+      if (!doc) return;
+      // Hide the inner document's scrollbars so the embed shows no scroll of
+      // its own; the frame is sized to the full content height below.
+      doc.documentElement.style.overflow = 'hidden';
+      const SHEET_W = 794; // 210mm A4 at 96dpi — the iframe's intrinsic width
+      const fit = () => {
+        const scale = wrap.clientWidth / SHEET_W;
+        const h = doc.body.scrollHeight; // body grows as fonts/QR render
+        frame.style.transform = 'scale(' + scale + ')';
+        frame.style.height = h + 'px';
+        wrap.style.height = (h * scale) + 'px';
+      };
+      fit();
+      // Re-fit on reflow (fonts/QR render late) and on window resize.
+      new ResizeObserver(fit).observe(doc.body);
+      window.addEventListener('resize', fit);
+    }}
+    style={{ width: '794px', border: 0, transformOrigin: 'top left' }}
+  ></iframe>
+</div>
 
 <a className="button button--primary button--lg" href="/cheatsheets/swarm-overview-cheatsheet.pdf" download>Download PDF</a>
-&nbsp;
-<a className="button button--secondary button--lg" href="/cheatsheets/overview/" target="_blank" rel="noopener">Open in a new tab</a>