ipfs · 2color · Mar 28, 2025 · Feb 21, 2025 · Feb 25, 2025 · Mar 3, 2025
diff --git a/.github/styles/pln-ignore.txt b/.github/styles/pln-ignore.txt
@@ -12,9 +12,11 @@ arbol('s)
 arg
 auditable
 audius
+astro
 auspinner
 bit[ss]wap
 bitswap
+blockchain
 blockchains
 blockstore
 bool
@@ -136,6 +138,7 @@ merkle
 merkleize
 merklizing
 merkleizing
+merkleizes
 merkleized
 merkleization
 metadata('s)
@@ -219,6 +222,7 @@ sneakernets
 stackparse
 stdout
 storj
+storacha
 Someguy
 subcommand
 substring
@@ -245,6 +249,7 @@ userspace
 vpns
 vscode
 vue
+Vuepress
 wantlist
 wantlists
 web

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -105,9 +105,8 @@ module.exports = {
               sidebarDepth: 1,
               collapsable: false,
               children: [
-                ['/quickstart/publish','Publish with IPFS (UI)'],
-                ['/quickstart/publish_cli', 'Publish with IPFS (command line)' ], 
                 ['/quickstart/retrieve','Retrieve with IPFS'],
+                ['/how-to/websites-on-ipfs/deploy-github-action', 'Deploy to IPFS with GitHub Actions' ],
               ]
             },
             {
@@ -124,9 +123,8 @@ module.exports = {
               sidebarDepth: 1,
               collapsable: false,
               children: [
-                ['/quickstart/publish','Publish with IPFS (UI)'],
-                ['/quickstart/publish_cli', 'Publish with IPFS (command line)' ],
                 ['/quickstart/retrieve','Retrieve with IPFS'],
+                ['/how-to/websites-on-ipfs/deploy-github-action', 'Deploy to IPFS with GitHub Actions' ],
 
               ]
             },
@@ -243,10 +241,10 @@ module.exports = {
               sidebarDepth: 1,
               collapsable: true,
               children: [
+                '/how-to/websites-on-ipfs/deploy-github-action',
+                '/how-to/websites-on-ipfs/custom-domains',
                 '/how-to/websites-on-ipfs/single-page-website',
                 '/how-to/websites-on-ipfs/multipage-website',
-                '/how-to/websites-on-ipfs/link-a-domain',
-                '/how-to/websites-on-ipfs/introducing-fleek',
                 '/how-to/websites-on-ipfs/static-site-generators',
                 '/how-to/websites-on-ipfs/redirects-and-custom-404s'
               ]

diff --git a/docs/.vuepress/redirects b/docs/.vuepress/redirects
@@ -44,6 +44,7 @@
 /how-to/troubleshoot-file-transfers /how-to/troubleshooting
 /how-to/run-ipfs-inside-docker /install/run-ipfs-inside-docker
 /how-to/ipfs-updater /install/command-line
+/how-to/websites-on-ipfs/link-a-domain /how-to/websites-on-ipfs/custom-domains
 /install/command-line-quick-start/ /how-to/command-line-quick-start
 /install/js-ipfs/ https://github.com/ipfs/helia/wiki
 /introduction/ /concepts

diff --git a/docs/README.md b/docs/README.md
@@ -5,42 +5,42 @@ description: The home page for developer documentation for IPFS, the InterPlanet
 
 # Welcome to the IPFS docs
 
-The InterPlanetary File System (IPFS) is a set of composable, peer-to-peer protocols for addressing, routing, and transferring [content-addressed](concepts/glossary.md#content-addressing) data in a decentralized file system. Many popular Web3 projects are built on IPFS - see the [ecosystem directory](https://ecosystem.ipfs.tech) for a list of some of these projects.
+IPFS is a set of building blocks for a better web. Open protocols to make your data smarter: content-addressed, verifiable, and unstoppable.
+
+On a more technical level, the InterPlanetary File System (IPFS) is a set of protocols for addressing, routing, and transferring data on the web, built on the ideas of [content-addressed](concepts/glossary.md#content-addressing) and peer-to-peer networking.
+
+Many popular projects are built on IPFS - see the [ecosystem directory](https://ecosystem.ipfs.tech) for a list of some of these projects.
 
 ## Get started
 
-You can quickly [store and retrieve data](#store-and-retrieve-data) and [interact with the network via a simple GUI app or a standard browser](#interact-with-the-network). If you'd rather develop applications, learn how to build IPFS-native apps or use standard HTTP in the [Build](#build) section.
+You can quickly [retrieve data](#retrieve-data) and [provide data](#provide-data) to the IPFS network, and [interact with the network](#interact-with-the-network) using a simple GUI app or a standard browser. If you'd rather develop applications, learn how to build IPFS-native apps or use standard HTTP in the [Build](#build) section.
 
-:::callout
-New to IPFS? Start with
-[the 3-page Basic Concepts](./concepts/README.md#learn-the-basics).
-:::
+### Retrieve data
 
-### Store and retrieve data
+Quickly retrieve data from the IPFS network, no programming required:
 
-Quickly store data and retrieve data, no complex applications or programming required:
+- Fetch data via it's [content identifier (CID)](concepts/glossary.md#cid)[using an IPFS gateway](./quickstart/retrieve.md).
+- Install the [IPFS Companion](./install/ipfs-companion.md) browser extension to add support for `ipfs://` and `ipns://` addresses to your browser.
 
-- Publish content to the IPFS network with a pinning service by following this [quickstart guide](./quickstart/publish.md).
-- Fetch data via it's <VueCustomTooltip label="An address used to point to data in IPFS, based on the content itself, as opposed to the location." underlined multiline is-medium>content identifier (CID)</VueCustomTooltip> [using an IPFS gateway](./quickstart/retrieve.md#fetching-the-cid-with-an-ipfs-gateway).
-- For long-term storage, use [Filecoin](https://docs.filecoin.io/), the peer-to-peer network with built-in economic incentives that stores data on IPFS.
+### Provide data
 
-### Interact with the network 
+Provide data to the IPFS network with IPFS Desktop or a pinning service:
 
-You can quickly interact the IPFS network using a simple GUI or a standard browser:
+- [Install IPFS Desktop which bundles an IPFS node (Kubo) and a UI to manage files, peers, and explore content on IPFS](./install/ipfs-desktop.md).
+- [Publish content to the IPFS network with IPFS Desktop](./how-to/desktop-app.md).
+- [Deploy static sites to the IPFS network with a GitHub Action](./how-to/websites-on-ipfs/deploy-github-action.md).
 
-- For a simple, easy-to-use GUI application that bundles an IPFS node, file manager, peer manager, and content explorer, use [IPFS Desktop](./install/ipfs-desktop.md).
-- Interact with the network using any Brave, Chrome, Edge, Firefox, Opera, and any other Chromium-based web browser using the [IPFS Companion browser extension](./install/ipfs-companion.md).
 
 ### Build
 
 You can build apps that leverage IPFS implementations, or use HTTP instead:
 
 #### Using IPFS
 
-Build an IPFS-native app using one of the many IPFS <VueCustomTooltip label="Software, written in any programming language, with functionality to process and transmit content-addressed data. Some implementations are optimized for specific use cases or devices, or use different subsystems to handle content-addressed data. There are multiple specifications in IPFS for handling content-addressed data, and not all implementations implement them." underlined multiline is-medium>implementations</VueCustomTooltip> and tools built by and for Web3 users:
+Build an IPFS-native app using one of the many IPFS [implementations](./concepts/ipfs-implementations.md) and tools:
 
-- To develop IPFS applications using Go and/or interact with IPFS from the terminal, use the [IPFS Kubo implementation in Go](./install/command-line.md). 
-- If you'd rather use JavaScript, try the [IPFS Helia implementation in JavaScript](https://github.com/ipfs/helia).
+- If you are familiar with JavaScript, checkout the [IPFS in web apps guide](./how-to/ipfs-in-web-apps.md), which covers how to use [Helia](https://github.com/ipfs/helia) and related libraries to build IPFS-native apps.
+- To develop IPFS applications using Go and/or interact with IPFS from the terminal, use the [IPFS Kubo implementation](./install/command-line.md).
 - Try any of the [many other tools and implementations](./concepts/ipfs-implementations.md), which are written in different languages and tailored to specific needs and use cases.
 
 #### Using HTTP

diff --git a/docs/concepts/dnslink.md b/docs/concepts/dnslink.md
@@ -29,7 +29,7 @@ For example, [`docs.ipfs.tech`](https://docs.ipfs.tech) loads because a `TXT` re
 
 ```shell
 dig +noall +answer TXT _dnslink.docs.ipfs.tech
-> _dnslink.docs.ipfs.tech. 30 IN TXT "dnslink=/ipfs/bafybeieenxnjdjm7vbr5zdwemaun4sw4iy7h4imlvvl433q6gzjg6awdpq"
+> _dnslink.docs.ipfs.tech. 30 IN TXT "dnslink=/ipfs/bafybeifld3uybj6azujisdnxu6cm7mombldpbt3au4g33nwnqx7dsgjrta"
 
 ```
 
@@ -47,7 +47,7 @@ For example, let's go back to when we looked up the DNS records for `_dnslink.do
 
 ```sh
 $ dig +noall +answer TXT _dnslink.docs.ipfs.tech
-_dnslink.docs.ipfs.tech.  34  IN  TXT "dnslink=/ipfs/QmVMxjouRQCA2QykL5Rc77DvjfaX6m8NL6RyHXRTaZ9iya"
+_dnslink.docs.ipfs.tech.  34  IN  TXT "dnslink=/ipfs/bafybeifld3uybj6azujisdnxu6cm7mombldpbt3au4g33nwnqx7dsgjrta"
 ```
 
 Based on that, this address:
@@ -59,9 +59,12 @@ Based on that, this address:
 Will get you this block:
 
 ```
-/ipfs/QmVMxjouRQCA2QykL5Rc77DvjfaX6m8NL6RyHXRTaZ9iya/introduction/
+/ipfs/bafybeifld3uybj6azujisdnxu6cm7mombldpbt3au4g33nwnqx7dsgjrta/introduction/
 ```
 
 ## Further Resources
 
+For more information on how to use DNSLink for your website or app, check out the [Custom domains and DNSLink](/how-to/websites-on-ipfs/custom-domains) guide.
+
 For a complete guide to DNSLink — including tutorials, usage examples, and FAQs — check out [dnslink.dev](https://dnslink.dev/).
+
diff --git a/docs/how-to/websites-on-ipfs/custom-domains.md b/docs/how-to/websites-on-ipfs/custom-domains.md
@@ -0,0 +1,46 @@
+---
+title: Custom domains and DNSLink
+description: Guide on how to use custom domains and DNSLink with IPFS deployed websites, allowing users to access your website or app via a custom domain.
+---
+
+# Custom domains and DNSLink
+
+By default, when you deploy a static web application to IPFS, it will be addressed with a CID. But CIDs are long, hard to remember, and not very user-friendly. For example,
+
+ - `https://bafybeifhgtpm6kmbyqszbardceszvkv5rsi3dodtuufpcfskzggekcfl2y.ipfs.inbrowser.link/` or
+ - `https://bafybeifhgtpm6kmbyqszbardceszvkv5rsi3dodtuufpcfskzggekcfl2y.ipfs.dweb.link/`.
+ - `ipfs://bafybeifhgtpm6kmbyqszbardceszvkv5rsi3dodtuufpcfskzggekcfl2y` (if you have the [IPFS Companion](https://github.com/ipfs/ipfs-companion) browser extension installed)
+
+To make your website or app easier to access, you can link a custom domain for your website or web app using two approaches that can be used in combination:
+
+- [CID signaling with DNSLink](#cid-signaling-with-dnslink): allowing users to access your website from IPFS Gateways using the custom domain, e.g. `https://ipfs.io/ipns/docs.ipfs.tech` (note that it will redirect to a subdomain gateway `https://docs-ipfs-tech.ipns.dweb.link/` to ensure origin isolation). With this approach, you can access your website from a local IPFS Gateway or the Service Worker Gateway, benefiting from local verification and all the other benefits of IPFS like peer-to-peer retrieval and censorship resistance.
+- [Access via a custom domain](#access-via-a-custom-domain) - Access your website via a custom domain name, e.g. `https://docs.ipfs.tech`. This is the common way for static websites to be deployed. Note that this approach does not benefit from the benefits of IPFS like peer-to-peer retrieval and censorship resistance if done without configuring DNSLink.
+
+The main difference between the two options is that CID signaling with DNSLink is mainly concerned with resolving a memorable domain name to a CID, while access via a custom domain is mainly concerned with accessing your website via a custom domain name. For most use cases, you probably want to use both approaches together or at the very least, use DNSLink to signal the CID for your website.
+
+This guide will walk you through the nuances of each of these options, and how to configure them for your app.
+
+### CID Signaling with DNSLink
+
+[DNSLink](../../concepts/dnslink.md) is a standard way to map human-readable domain names (DNS) to CIDs. For example, for the IPFS Docs, `docs.ipfs.tech`, the DNSLink record is a TXT record at `_dnslink.docs.ipfs.tech` with the value `dnslink=/ipfs/bafybeicv5tbyeahgm4pyskd2nverwsqxpiqloikqrufvof7vausglw6avm` (the CID will likely be different once you read this guide).
+
+The main benefit of DNSLink is that it allows users to determine the latest CID for a given domain name, while leaving it up to the user how to retrieve the deployment addressed by the CID. For example, a user might have a local IPFS node, and want to access the latest deployment of your app, they can do so by resolving the DNSLink record and fetching the content from their local node. `http://localhost:8080/ipns/docs.ipfs.tech` will serve the CID found in the DNSLink record.
+
+When a DNSLink record is present, any IPFS gateway (local or public) can take the DNS name and resolve it to the CID, and serve the content, for example, both `https://inbrowser.link/ipns/docs.ipfs.tech` and `https://dweb.link/ipns/docs.ipfs.tech` will serve the same site, albeit with different origins.
+
+If you run your own IPFS node, such as [IPFS Desktop](../../install/ipfs-desktop.md) or [Kubo](../../install/command-line.md), and load the site from a local gateway at `http://localhost:8080/ipns/docs.ipfs.tech`, you benefit from the resilience and censorship resistance of the IPFS network, because it's content addressed (addressed by CID) rather than being tied to a canonical origin. As long as there's at least one reachable provider for the CID, and use a trusted [DNS over HTTPS resolver](https://github.com/ipfs/kubo/blob/master/docs/config.md#dnsresolvers), you can access the site.
+
+Loading the site this way ties the website's cookies, storage, and Web API permissions to the [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin) of a specific gateway. When using public gateways, the user experience can vary depending on the gateway's origin, which may impact app functionality, including cookies, storage, and CORS access to external APIs. That is why a local gateway is advantageous, as it does not depend on external domains or origins.
+
+## Access via a custom domain
+
+In the previous section, we discussed how DNSLink can be used to signal the CID for a domain name, while leaving it up to the user how to retrieve the content, be it a local node, service worker gateway or any other [public recursive gateway](https://docs.ipfs.tech/concepts/ipfs-gateway/#recursive-vs-non-recursive-gateways).
+
+With this approach, users can access your website via a custom domain name, e.g. `https://docs.ipfs.tech` but you can't easily verify the content, or load the site from a local node. Hence, it is recommended to use this as a complement to CID signaling with DNSLink.
+
+To provide access to the app directly via the custom domain, you have the following options:
+
+1. Self-host both the IPFS provider (e.g. [Kubo](https://github.com/ipfs/kubo)) and the HTTP gateway (e.g. [Kubo](https://github.com/ipfs/kubo) or [Rainbow](https://github.com/ipfs/rainbow/)). Deploy an IPFS Gateway that supports DNSLink resolution and point the `CNAME`/`A` DNS record for your custom domain to it and  update the `TXT` record on `_dnslink` subdomain to match CID of your website. Set up CI automation to update TXT record every time your CID changes. You will likely want to also configure TLS with a reverse proxy like Caddy or use a CDN like Cloudflare for TLS termination.
+2. Use a service like Fleek which encompasses both DNSLink and traditional web hosting (HTTP + TLS + CDN + [automatic DNSLink management](https://fleek.xyz/docs/platform/domains/#dnslink)).
+3. Deploy the site to a web hosting service like [Cloudflare Pages](https://pages.cloudflare.com/) or [GitHub Pages](https://pages.github.com/) with a custom domain (pointing and configuring the `CNAME`/`A` record for your custom domain on the web hosting service), while managing the DNSLink `TXT` record on `_dnslink` subdomain separately, essentially getting the benefits of both IPFS and traditional web hosting. Remember to set up CI automation to update the DNSLink `TXT` record for every deployment that changes the CID.
+