Edits

Author: ElPaisano

docs/how-to/detect-ipfs-on-web.md

@@ -1,18 +1,24 @@
-# Discover IPFS content from web2
+---
+title: Discover IPFS content from Web2
+description: Learn how to add support for content-addressed IPFS resources in web browsers and other user agents.
+---
 
-Below is the suggested heuristic for detecting content-addressed resources on the web, and presenting additional user interface for interacting with that content.
+# Discover IPFS content from Web2
 
-The goal of this page is to provide some suggestions and best practices for web browsers and other [user agents](https://en.wikipedia.org/wiki/User_agent) that are interested in adding support for [content-addressed resources on the Web](/how-to/address-ipfs-on-web).
+The goal of this page is to provide some suggestions and best practices for Web 2 web browsers and other [user agents](https://en.wikipedia.org/wiki/User_agent) that are interested in adding support for [content-addressed resources](/how-to/address-ipfs-on-web).
 
 ## Detecting content-addressed resources
 
-In many cases IPFS resources can be detected just by looking at the URI, especially if it is an HTTP URL pointing at a public gateway. This allows a browser to upgrade the transport protocol to IPFS, and remove the need for sending an HTTP request to a remote server.
+In many cases, IPFS resources can be detected just by looking at the URI, especially if it is an HTTP URL pointed at a public gateway. This allows a browser to upgrade the transport protocol to IPFS, and removes the need to send an HTTP request to a remote server.
 
-The high level heuristic is to check, in order:
-- Does the `URL` follow [path or subdomain gateway](/how-to/address-ipfs-on-web/) convention?
-- If not, does [DNSLink](/concepts/dnslink/) with an IPFS path exist for `URL.hostname`?
+### Methodology
 
-If any of the above is true, a user agent should be able to find a content path that can be used for data retrieval over IPFS. See the illustration below.
+To determine if a resource is an IPFS resource, answer the following questions in order:
+
+1. Does the `URL` follow [path or subdomain gateway](/how-to/address-ipfs-on-web/) convention?
+1. If not, does [DNSLink](/concepts/dnslink/) with an IPFS path exist for `URL.hostname`?
+
+If you answered yes to either of the above questions, a user agent should be able to find a content path that can be used for data retrieval over IPFS, as described in the illustration below:
 
 ```mermaid
 flowchart TD
@@ -77,7 +83,9 @@ flowchart TD
     PathFromHeader --> PotentialContentPath
 ```
 
-## What to do with detected paths?
+## What to do with detected paths
+
+What you do with the detected IPFS resource path depends on the type of path.
 
 ### Immutable `/ipfs/cid/..`
 
@@ -101,27 +109,20 @@ flowchart TD
 
 ## FAQ
 
-- What if a browser does not support `ipfs://` and `ipns://` natively?
-  - Implementation can use a [HTTP Gateway](/reference/http/gateway/) as a fallback: convert them to `//gatewayhost/ipxs/id/..` paths, or leverage the built-in URI router at `//gatewayhost/ipfs/?uri=%s`
-- Why should `?query` or `#hash` from the original HTTP URL be preserved?
-  - Link could point at specific `#section` of  a longer article. It is also common for JS running on a page to use `?query` and `#hash` for navigation and ad-hoc storage for some state.
-- Should user agent redirect when URL does not match gateway convention, `URL.hostname` does not have a valid DNSLink, but `X-Ipfs-Path` is present in HTTP response AND points at immutable `/ipfs/cid`?
-  - This is an edge case, and we've seen that it is often a misconfiguration caused by invalid/missing DNSLink that could lead to bad UX when automatic redirect is involved: user ends up on immutable copy of a website, bookmark it or keep tab open, and miss updates when DNSLink setup is fixed.
-  - It is suggested to not redirect this edge case, or provide a setting that controls this type of redirect. Usually, showing "Open via IPFS" in the user interface is enough for this case.
+**What if a browser does not support `ipfs://` and `ipns://` natively?** Implementations can use an [HTTP Gateway](/reference/http/gateway/) as a fallback, convert ththe path to `//gatewayhost/ipxs/id/..`-type paths, or leverage the built-in URI router at `//gatewayhost/ipfs/?uri=%s`
+
+**Why should `?query` or `#hash` from the original HTTP URL be preserved?** The link could point at specific `#section` of  a longer article. It is also common for JavaScript running on a page to use the `?query` and `#hash` for navigation and ad-hoc storage of some state.
+
+**Should a user agent redirect when the URL does not match gateway convention, `URL.hostname` does not have a valid DNSLink, but `X-Ipfs-Path` is present in HTTP response AND points at an immutable `/ipfs/cid`?** This is an edge case, and we've seen that it is often a misconfiguration caused by an invalid or missing DNSLink that could lead to bad UX when automatic redirect is involved. The user ends up on an immutable copy of a website, bookmarks it or keeps tabs open, and misses updates when DNSLink setup is fixed. It is suggested to not redirect this edge case, or provide a setting that controls this type of redirect. Usually, showing "Open via IPFS" in the user interface is enough for this case.
 
 ## Implementation examples
 
 ### Brave
 
-[IPFS is supported in Brave since 2021](https://brave.com/brave-integrates-ipfs/). Current features include `ipfs://` and `ipns://` URI support, ability to resolve them using a public or local gateway, opt-in Gateway and DNSLink redirects, and "Open via IPFS" button in the address bar:
+[Brave has supported IPFS since 2021](https://brave.com/brave-integrates-ipfs/). Current features include `ipfs://` and `ipns://` URI support, ability to resolve this type of address using a public / local gateway, opt-in Gateway and/or DNSLink redirects, and an **Open via IPFS** button in the address bar:
 
-> ![Open via IPFS in Brave addressbar](https://user-images.githubusercontent.com/157609/110859368-9a0d7300-82bb-11eb-934d-4e38718dbacb.png)
+> ![Open via IPFS in Brave address bar](https://user-images.githubusercontent.com/157609/110859368-9a0d7300-82bb-11eb-934d-4e38718dbacb.png)
 
 ### IPFS Companion
 
-Firefox and Chromium-based browsers such as Google Chrome, Microsoft Edge can be augumented with [IPFS Companion](/install/ipfs-companion/) browser extension.
-
-It provides detection of IPFS resources, redirect functionality, and a handy UI:
-
-> ![Quick runthrough of basic IPFS Companion features](https://gateway.ipfs.io/ipfs/QmSsGphTN1eWMhkFFNFb23jWTXyhNbo47PF9FbmC6ZaRNg)
-
+Firefox and Chromium-based browsers such as Google Chrome or Microsoft Edge can be augumented with [IPFS Companion](/install/ipfs-companion/) browser extension, which allows them to detect IPFS content.