ipfs · 2color · Jul 25, 2024 · Jul 25, 2024 · Jul 25, 2024 · Jul 25, 2024
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -5,11 +5,11 @@ const SPEEDCURVE_ID = process.env.SPEEDCURVE_ID || ''
 const pageSuffix = '/'
 
 const installMenuChildren = [
-  ['/install/command-line','IPFS Kubo for Go'],
-  ['/install/run-ipfs-inside-docker', 'IPFS Kubo in Docker'],
+  ['/install/ipfs-desktop', 'IPFS Desktop (Kubo)'],
+  ['/install/command-line','Kubo (CLI) '],
+  ['/install/run-ipfs-inside-docker', 'Kubo in Docker'],
   ['https://github.com/ipfs/helia','IPFS Helia for JavaScript'],
   ['https://iroh.computer/docs/install/', "IPFS Iroh for Rust"],
-  ['/install/ipfs-desktop', 'IPFS Desktop App'],
   ['/install/ipfs-companion', 'IPFS Companion Browser Extension'],
   ['/install/server-infrastructure', 'IPFS Cluster']
 ]
@@ -44,7 +44,7 @@ module.exports = {
     defaultImage: '/images/social-card.png',
     author: {
       name: 'IPFS Team',
-      twitter: '@ipfsbot'
+      twitter: '@ipfs'
     },
     keywords:
       'IPFS, dweb, protocol, libp2p, ipld, multiformats, bitswap, decentralized web, InterPlanetary File System, dapp, documentation, docs, Protocol Labs',
@@ -253,12 +253,12 @@ module.exports = {
               ]
             },
             {
-              title: 'IPFS in the browser',
+              title: 'IPFS on the web',
               sidebarDepth: 1,
               collapsable: true,
               children: [
+                '/how-to/ipfs-on-the-web',
                 '/how-to/address-ipfs-on-web',
-                '/how-to/browser-tools-frameworks'
               ]
             },
             {
@@ -275,7 +275,7 @@ module.exports = {
               collapsable: true,
               children: [
                 '/how-to/gateway-best-practices',
-                '/how-to/gateway-troubleshooting'
+                '/how-to/gateway-troubleshooting',
               ]
             },
             {
@@ -309,6 +309,10 @@ module.exports = {
           '/reference/': [
             '/reference/diagnostic-tools',
             '/reference/http/gateway',
+            {
+              path: 'https://specs.ipfs.tech/architecture/principles/',
+              title: 'IPFS Principles',
+            },
             '/reference/js/api',
             '/reference/go/api',
             {
@@ -323,8 +327,11 @@ module.exports = {
               collapsable: true,
               path: '/reference/kubo/rpc'
             },
-            '/reference/kubo-rpc-cli.md'
-
+            '/reference/kubo-rpc-cli.md',
+            {
+              path: 'https://specs.ipfs.tech',
+              title: 'IPFS Specifications',
+            },
           ],
           '/community/': [
             ['/community/', 'Join the community'],

diff --git a/docs/.vuepress/redirects b/docs/.vuepress/redirects
@@ -40,6 +40,7 @@
 /guides/guides/addressing/ /how-to/address-ipfs-on-web
 /guides/guides/install/ /install
 /how-to/host-single-page-site /how-to/websites-on-ipfs/single-page-website
+how-to/browser-tools-frameworks /how-to/ipfs-on-the-web/
 /how-to/troubleshoot-file-transfers /how-to/troubleshooting
 /how-to/run-ipfs-inside-docker /install/run-ipfs-inside-docker
 /install/command-line-quick-start/ /how-to/command-line-quick-start

diff --git a/docs/concepts/glossary.md b/docs/concepts/glossary.md
@@ -76,7 +76,7 @@ A Bootstrap Node is a trusted peer on the IPFS network through which an IPFS nod
 
 ### CAR
 
-The CAR (Content Addressable aRchives) is a format for serialized representation of any [IPLD](#ipld) [DAG](#dag). Typically in a file with a .car filename extension or a byte stream marked as [application/vnd.ipld.car](https://www.iana.org/assignments/media-types/application/vnd.ipld.car) media type. [More about CAR](https://ipld.io/specs/transport/car/)
+The CAR (Content Addressable aRchives) is a format for serialized representation of any [IPLD](#ipld) [DAG](#dag). The CAR format is a way of packaging up content-addressed data into archive files that can be easily stored and transferred. Typically in a file with a `.car` filename extension or a byte stream marked as [application/vnd.ipld.car](https://www.iana.org/assignments/media-types/application/vnd.ipld.car) media type. [More about CAR](https://ipld.io/specs/transport/car/)
 
 ### CAR v1
 
@@ -208,7 +208,7 @@ An experimental data store used when `--nocopy` is passed to `ipfs add`. It stor
 
 ### Gateway
 
-An IPFS Gateway acts as a bridge between traditional web browsers and IPFS. Through the gateway, users can browse files and websites stored in IPFS as if they were stored on a traditional web server. [More about Gateway](../concepts/ipfs-gateway.md) and [addressing IPFS on the web](../how-to/address-ipfs-on-web.md)
+An IPFS Gateway acts as a bridge between HTTP-based protocols and IPFS. Through the gateway, users can browse files and websites stored in IPFS as if they were stored on a HTTP web server. [More about Gateway](../concepts/ipfs-gateway.md) and [addressing IPFS on the web](../how-to/address-ipfs-on-web.md)
 
 ### Garbage Collection
 
@@ -298,6 +298,10 @@ In IPFS and [IPLD](#ipld), a _link_ usually means a pointer to some [CID](#cid).
 
 ## M
 
+### IPFS Mainnet
+
+IPFS Mainnet is a term used to describe the default or "main" network that many IPFS implementations connect to. Mainnet is a subset of all the [IPFS implementations](https://specs.ipfs.tech/architecture/principles/#ipfs-implementation-requirements) and typically includes implementations that connect to the [Amino DHT](#amino) and support [Bitswap](#bitswap), [UnixFS](#unixfs), and the [IPFS Gateway](#gateway). This has mostly been assumed for the IPFS network and is not emphasized for anyone other than protocol experts. Nonetheless, IPFS Mainnet is a useful distinction in a world of many [IPFS implementations](../concepts/implementations.md) with varying degrees of interoperability.
+
 ### Merkle-DAG
 
 The Merkle-DAG is a computer science data structure used at the core of IPFS files/block storage. Merkle-DAGs create a hash to their content, known as a [Content Identifier](#cid). [More about Merkle-DAG](merkle-dag.md)

diff --git a/docs/how-to/browser-tools-frameworks.md b/docs/how-to/browser-tools-frameworks.md
diff --git a/docs/how-to/ipfs-on-the-web.md b/docs/how-to/ipfs-on-the-web.md
@@ -0,0 +1,46 @@
+---
+title: IPFS on the web
+description: How to use IPFS on the web, including IPFS retrieval and pinning in browsers using implementations.
+---
+
+# IPFS on the web
+
+## Challenges with IPFS on the Web
+
+One of the main benefits of IPFS is that CIDs allow you to fetch data from anyone **trustlessly** through hash verification. This foundation enables IPFS to function as a permissionless peer-to-peer network. 
+
+However, making all of this work on the web is tricky. While web browsers have the widest proliferation as an application runtime, they impose many restrictions on what web pages can do. For example, a web page cannot just open TCP/UDP connections. It is mostly constrained to HTTP, WebSockets, WebRTC, and most recently WebTransport. There are good reasons for this like security and resource management, but ultimately, it means that **using IPFS on the Web is different to IPFS in native binaries.**
+
+Thus, the Web is both a **resource-constrained and API-constrained** environment. So practically everything on this page is applicaable
+
+## Onboarding, Retrieving, and Providing
+
+Ultimately, there are three things that you do with IPFS:
+- Onboard data, i.e. take arbitrary data, chunk it, and structure it as a Merkle DAG represented by a single CID. 
+- Retrieve files and arbitrary data. Given a CID, you use IPFS to find providers (peers who share the block), connect to them *somehow*, fetch the blocks, and verify from peers who have the CID. Once that's all done, you save the block locally. 
+- Provide the block to others.
+
+### You probably don't want to rely on the web for providing
+
+Browsers make for lousy servers. It's almost impossible to make a web page "dialable", i.e. allow other computers to connect to it (the exception is WebRTC with many caveats). 
+
+For this reason, for CIDs to it's recommended to delegate providing to an external server that runs reliably and has a public IP. That can be a Kubo node that you run, or a [pinning service](../concepts/persistence.md#pinning-services). 
+
+## Onboarding
+
+Even when relying on another server for providing, it's recommended to handle chunking and Merkle-DAG construction locally in the browser and uploading a [CAR file](../concepts/glossary.md#car). This reduces the trust surface and allows you to know the CID ahead of the upload.
+
+## Retrieval
+
+### With Verified-fetch
+
+<iframe height="300" style="width: 100%;" scrolling="no" title="Resolving and Fetching a IPNS with @helia/verified-fetch example" src="https://codepen.io/2color/embed/QWXKZGx?default-tab=html%2Cresult" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/2color/pen/QWXKZGx">
+  Resolving and Fetching a IPNS with @helia/verified-fetch example</a> by Daniel Norman (<a href="https://codepen.io/2color">@2color</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
+
+
+
+
+
diff --git a/docs/install/ipfs-desktop.md b/docs/install/ipfs-desktop.md
@@ -5,9 +5,9 @@ description: IPFS Desktop gives you all the power of IPFS in a convenient deskto
 
 # Install the IPFS Desktop App
 
-**IPFS Desktop bundles an IPFS node, file manager, peer manager, and content explorer into a single, easy-to-use application.**
+**IPFS Desktop bundles a Kubo IPFS node, file manager, peer manager, and content explorer into a single, easy-to-use application.**
 
-Use IPFS Desktop to get acquainted with IPFS without needing to touch the terminal — or, if you're already experienced, use the powerful menubar/taskbar shortcuts alongside the command line to make your IPFS workflow faster.
+Use IPFS Desktop to get acquainted with [Kubo](https://github.com/ipfs/kubo/), a popular  IPFS implementation without needing to touch the terminal — or, if you're already experienced, use the powerful menubar/taskbar shortcuts alongside the command line to make your IPFS workflow faster.
 
 If you already have an IPFS node on your computer, IPFS Desktop will act as a control panel and file browser for that node. If you don't have a node, it'll install one for you. And either way, IPFS Desktop will automatically check for updates.