ipfs · lidel · May 29, 2026 · May 29, 2026 · May 29, 2026 · May 29, 2026
diff --git a/.github/styles/pln-ignore.txt b/.github/styles/pln-ignore.txt
@@ -353,3 +353,14 @@ youtube
 zarr
 Zeeshan
 Zelenka
+deserializes
+dnslinks
+env
+fastly
+hotlinked
+iostat
+iotop
+navigations
+speedtest
+subresource
+subresources
diff --git a/.github/workflows/reveiwdog-languagetool.yml b/.github/workflows/reveiwdog-languagetool.yml
@@ -13,7 +13,14 @@ jobs:
         uses: reviewdog/action-languagetool@v1
         with:
           github_token: ${{ secrets.github_token }}
-          reporter: github-pr-review
+          # github-pr-check posts findings as check-run annotations instead of
+          # review comments. Each run replaces the previous run's annotations, so
+          # pushes do not pile up duplicate comments and fixed findings disappear
+          # on the next run, rather than lingering as stale review threads.
+          reporter: github-pr-check
           level: info
+          # Action defaults plus rules that misfire on code fences (```js), inline
+          # code, shell snippets (quotes), and domain names (ipfs.io) in our docs.
+          disabled_rules: WHITESPACE_RULE,EN_QUOTES,DASH_RULE,WORD_CONTAINS_UNDERSCORE,UPPERCASE_SENTENCE_START,ARROWS,COMMA_PARENTHESIS_WHITESPACE,UNLIKELY_OPENING_PUNCTUATION,SENTENCE_WHITESPACE,CURRENCY,EN_UNPAIRED_BRACKETS,PHRASE_REPETITION,PUNCTUATION_PARAGRAPH_END,METRIC_UNITS_EN_US,ENGLISH_WORD_REPEAT_BEGINNING_RULE,FILE_EXTENSIONS_CASE,EN_UNPAIRED_QUOTES,A_INSTALL,LC_AFTER_PERIOD
           patterns: 'docs/**/*.md'
 
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -293,6 +293,7 @@ module.exports = {
               collapsable: true,
               children: [
                 '/how-to/gateway-best-practices',
+                '/how-to/replace-public-gateways-with-self-hosted-ipfs',
                 '/how-to/troubleshooting',
               ]
             },

diff --git a/docs/concepts/ipfs-gateway.md b/docs/concepts/ipfs-gateway.md
@@ -43,6 +43,8 @@
 
 For a list of public gateways, see the [IPFS Gateways Checker](https://ipfs.fyi/gateways).
 
+If your app already calls a public gateway and you want to run your own instead, see [Replace public gateways with self-hosted IPFS](../how-to/replace-public-gateways-with-self-hosted-ipfs.md).
+
 ## Gateway types
 
 There are multiple gateway types, each with specific use case, security, performance, and functional implications.
@@ -189,7 +191,7 @@
 
 ## Working with gateways
 
-For more information on working with gateways, see [best practices](../how-to/gateway-best-practices.md) and [troubleshooting](../how-to/gateway-troubleshooting.md).
+For more information on working with gateways, see [best practices](../how-to/gateway-best-practices.md) and [troubleshooting](../how-to/troubleshooting.md).
 
 ## Implementing gateways
 

diff --git a/docs/concepts/public-utilities.md b/docs/concepts/public-utilities.md
@@ -12,6 +12,8 @@
 
 These utilities make it easier to retrieve data from the IPFS network in resource-constrained environments such as browsers and low-powered devices.
 
+They are a great way to get started. When your app outgrows best-effort traffic and you want infrastructure you control, see [Replace public gateways with self-hosted IPFS](../how-to/replace-public-gateways-with-self-hosted-ipfs.md).
+
 ## Public IPFS Gateways
 
 The IPFS Foundation provides the following public gateways:

diff --git a/docs/how-to/README.md b/docs/how-to/README.md
@@ -7,6 +7,7 @@ description: Hands-on guides to using and developing with IPFS to build decentra
 
 See the site navigation menu for all our how-tos, organized by topic area, including favorites like these:
 
+- **Move off public gateways** by [replacing `ipfs.io` and `dweb.link` with self-hosted IPFS](replace-public-gateways-with-self-hosted-ipfs.md)
 - **Customize your install** by [configuring a node](configure-node.md), modifying the [bootstrap list](modify-bootstrap-list.md), and more
 - **Learn how to manage files** in IPFS with tutorials on concepts like [pinning](pin-files.md), how to [work with blocks](work-with-blocks.md), learning how to [content address data sets](content-addressing-data-sets.md).
 - **Publish scientific data** by exploring the [scientific data and IPFS landscape guide](scientific-data/landscape-guide.md) or learning how to [publish geospatial Zarr data with IPFS](scientific-data/publish-geospatial-zarr-data.md)

diff --git a/docs/how-to/address-ipfs-on-web.md b/docs/how-to/address-ipfs-on-web.md
@@ -20,7 +20,7 @@ For example:
 https://ipfs.io/ipfs/bafybeihkoviema7g3gxyt6la7vd5ho32ictqbilu3wnlo3rs7ewhnp7lly
 ```
 
-A [self-hosted local gateway](https://docs.ipfs.tech/install/) can also be used, instead of `ipfs.io`. 
+A [self-hosted local gateway](https://docs.ipfs.tech/install/) can also be used, instead of `ipfs.io`. To move an existing app off the public gateways, see [Replace public gateways with self-hosted IPFS](./replace-public-gateways-with-self-hosted-ipfs.md).
 
 ## IPFS addressing in brief
 

diff --git a/docs/how-to/gateway-best-practices.md b/docs/how-to/gateway-best-practices.md
@@ -23,6 +23,8 @@ Any form of gateway provides a bridge for apps without native support of IPFS. B
 
 If you are running an IPFS node that is also configured as an IPFS gateway, each of the tips below can help improve the discovery and retrievability of your CIDs.
 
+If you are moving off the public `ipfs.io` or `dweb.link` gateways, see [Replace public gateways with self-hosted IPFS](./replace-public-gateways-with-self-hosted-ipfs.md) for a drop-in migration path.
+
 - Pin your CIDs to multiple IPFS nodes to ensure reliable availability and resilience to failures of nodes and network partitions. To make pinning easier, use the vendor-agnostic [Pinning Service OpenAPI Specification](https://ipfs.github.io/pinning-services-api-spec/) that is already [supported by many IPFS node implementations, client libraries, and existing pinning services](https://github.com/ipfs/pinning-services-api-spec#adoption).
 - Use a custom domain that you control as your IPFS gateway for flexibility in implementing performance optimizations. You can do this using one of the following methods:
   - Point a domain you control like `mydomain.ipfs.yourdomain.io` to a reverse proxy like nginx, which will proxy requests to a public gateway, allowing you to switch public gateways if there's downtime.

diff --git a/docs/how-to/ipfs-in-web-apps.md b/docs/how-to/ipfs-in-web-apps.md
@@ -68,7 +68,7 @@ From a high level, there are several ways to retrieve data with IPFS in web appl
 
 - Using the [Verified Fetch](https://www.npmjs.com/package/@helia/verified-fetch) library, which was modelled after the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) and returns [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) objects, with the main difference being that it allows you to fetch data by CID, abstracting away the details of content routing, transports and retrieval. For more examples and background see the [release blog post](https://blog.ipfs.tech/verified-fetch/).
 - Using the [Helia](https://github.com/ipfs/helia/) library, which is the foundation for the `@helia/verified-fetch` library, and provides a more comprehensive and modular API for interacting with the IPFS network, beyond just retrieval.
-- Using public recursive gateways, e.g. `ipfs.io` with HTTP. This is not recommended for most use cases, because it forgoes the verifiability and trustlessness enabled by content addressing. Granted, it might be the easiest way to retrieve data in a web application, but is also the most fraught with security and centralization concerns.
+- Using public recursive gateways, e.g. `ipfs.io` with HTTP. This is not recommended for most use cases, because it forgoes the verifiability and trustlessness enabled by content addressing. Granted, it might be the easiest way to retrieve data in a web application, but is also the most fraught with security and centralization concerns. If your app already fetches from `ipfs.io` or `dweb.link` this way, see [Replace public gateways with self-hosted IPFS](./replace-public-gateways-with-self-hosted-ipfs.md) for a drop-in move to `@helia/verified-fetch`.
 
 ### Example: Image retrieval with Verified Fetch