chore: update format and accept docs (#1897)

* chore: update format and accept docs

updating example to match SHOULD from specs
ipfs/specs#478

* chore: fix lint and broken links

* chore: update links to specs.ipfs.tech website

Author: lidel

docs/reference/http/gateway.md

@@ -5,14 +5,14 @@ description: HTTP Gateway API reference for IPFS clients.
 
 # HTTP Gateway reference
 
-Gateways provide implementation and runtime agnostic HTTP interface for retrieving [content-addressed](../../concepts/glossary/#content-addressing) data from IPFS with regular HTTP clients and libraries.
+Gateways provide implementation and runtime agnostic HTTP interface for retrieving [content-addressed](../../concepts/glossary.md#content-addressing) data from IPFS with regular HTTP clients and libraries.
 
 
 ## API
 
 ### `GET /ipfs/{cid}[/{path}][?{params}]`
 
-- `cid` is a [CID](../../concepts/glossary/#cid), the root identifier of the requested content path
+- `cid` is a [CID](../../concepts/glossary.md#cid), the root identifier of the requested content path
 - `path` – optional path under the root CID
 
 Optional query parameters:
@@ -23,7 +23,7 @@ Optional query parameters:
 
 ::: tip Before you continue
 
-Make sure you understand [how to address IPFS on the web](../../how-to/address-ipfs-on-web/) and the differences between [Path Gateways](../../how-to/address-ipfs-on-web/#path-gateway) and [Subdomain Gateways](../../how-to/address-ipfs-on-web/#subdomain-gateway).
+Make sure you understand [how to address IPFS on the web](../../how-to/address-ipfs-on-web.md) and the differences between [Path Gateways](../../how-to/address-ipfs-on-web.md#path-gateway) and [Subdomain Gateways](../../how-to/address-ipfs-on-web.md#subdomain-gateway).
 
 :::
 
@@ -50,7 +50,7 @@ When fetching a CID directly, one can include a `filename` parameter with file n
 
 ### Trustless, verifiable retrieval
 
-Clients capable of verifying content-addressed data on their own, should use [application/vnd.ipld.raw](https://www.iana.org/assignments/media-types/application/vnd.ipld.raw) and [application/vnd.ipld.car](https://www.iana.org/assignments/media-types/application/vnd.ipld.car) response types (raw [blocks](../../concepts/glossary/#block) and [CARs](../../concepts/glossary/#car)) and always ask for CIDs directly (`/ipfs/{cid}`).
+Clients capable of verifying content-addressed data on their own, should use [application/vnd.ipld.raw](https://www.iana.org/assignments/media-types/application/vnd.ipld.raw) and [application/vnd.ipld.car](https://www.iana.org/assignments/media-types/application/vnd.ipld.car) response types (raw [blocks](../../concepts/glossary.md#block) and [CARs](../../concepts/glossary.md#car)) and always ask for CIDs directly (`/ipfs/{cid}`).
 
 ::: callout
 
@@ -60,28 +60,28 @@ This mode of operation removes the need for trusting gateway returns correct dat
 
 #### Example: fetching an entire DAG as a CAR stream from a public gateway
 
-Using `Accept` HTTP header with [application/vnd.ipld.car](https://www.iana.org/assignments/media-types/application/vnd.ipld.car) type:
+To request [application/vnd.ipld.car](https://www.iana.org/assignments/media-types/application/vnd.ipld.car) response type:
 
 ```bash
-$ curl -H "Accept: application/vnd.ipld.car" "https://ipfs.io/ipfs/bafybeiakou6e7hnx4ms2yangplzl6viapsoyo6phlee6bwrg4j2xt37m3q" > dag.car
+$ curl -H "Accept: application/vnd.ipld.car" "https://ipfs.io/ipfs/bafybeiakou6e7hnx4ms2yangplzl6viapsoyo6phlee6bwrg4j2xt37m3q?format=car" -L > dag.car
 $ ipfs dag import dag.car
 ```
 
 ::: tip
 
-An alternative is to pass `?format=car` URL parameter:
+A Client SHOULD include the [`format` query parameter](https://specs.ipfs.tech/http-gateways/trustless-gateway/#format-request-query-parameter) in the request URL, ideally in addition to the [`Accept` header](https://specs.ipfs.tech/http-gateways/trustless-gateway/#accept-request-header). This provides the best interoperability and ensures consistent HTTP cache behavior across various gateway implementations.
 
 <https://ipfs.io/ipfs/bafybeiakou6e7hnx4ms2yangplzl6viapsoyo6phlee6bwrg4j2xt37m3q?format=car>
 
-::: 
+:::
 
 ::: tip Verify CAR without running full IPFS node
 
 CAR verification does not require running IPFS node. Clients can leverage standalone tools and libraries such as [ipfs-car](https://www.npmjs.com/package/ipfs-car):
 
 ```bash
 $ npm i -g ipfs-car
-$ curl "https://ipfs.io/ipfs/bafybeiakou6e7hnx4ms2yangplzl6viapsoyo6phlee6bwrg4j2xt37m3q?format=car" | ipfs-car
+$ curl "https://ipfs.io/ipfs/bafybeiakou6e7hnx4ms2yangplzl6viapsoyo6phlee6bwrg4j2xt37m3q?format=car" -L | ipfs-car
 $ ls ./bafybeiakou6e7hnx4ms2yangplzl6viapsoyo6phlee6bwrg4j2xt37m3q/
 1007 - Sustainable - alt.txt
 1007 - Sustainable - transcript.txt
@@ -92,46 +92,45 @@ $ ls ./bafybeiakou6e7hnx4ms2yangplzl6viapsoyo6phlee6bwrg4j2xt37m3q/
 
 #### Example: fetching a single raw block from a public gateway
 
-Using `Accept` HTTP header with [application/vnd.ipld.raw](https://www.iana.org/assignments/media-types/application/vnd.ipld.raw) type:
+To request [application/vnd.ipld.raw](https://www.iana.org/assignments/media-types/application/vnd.ipld.raw) response type:
 
 ```bash
-$ curl -H "Accept: application/vnd.ipld.raw" "https://ipfs.io/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi" > raw-block.bin
+$ curl -H "Accept: application/vnd.ipld.raw" "https://ipfs.io/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi?format=raw" -L > raw-block.bin
 $ ipfs block put raw-block.bin
 bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
 ```
 
-
 ::: tip
 
-An alternative is to pass `?format=raw` URL parameter:
+A Client SHOULD include the [`format` query parameter](https://specs.ipfs.tech/http-gateways/trustless-gateway/#format-request-query-parameter) in the request URL, ideally in addition to the [`Accept` header](https://specs.ipfs.tech/http-gateways/trustless-gateway/#accept-request-header). This provides the best interoperability and ensures consistent HTTP cache behavior across various gateway implementations.
 
 <https://ipfs.io/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi?format=raw>
 
 :::
 
 ## Specifications
 
-The HTTP Gateway specification for IPFS implementers is available in [ipfs/specs repository](https://github.com/ipfs/specs/blob/main/http-gateways/#readme).
+The HTTP Gateway specification for IPFS implementers is available at [specs.ipfs.tech](https://specs.ipfs.tech/http-gateways/).
 Below are links for the most useful specifications.
 
 
 ### HTTP
 
 These are "low level" gateways that expose IPFS resources over HTTP protocol.
 
-* [Path Gateway](https://github.com/ipfs/specs/blob/main/http-gateways/PATH_GATEWAY.md) ← **START HERE**, other types of gateway are specified as a delta against this specification.
-* [Trustless Gateway](https://github.com/ipfs/specs/blob/main/http-gateways/TRUSTLESS_GATEWAY.md) is a subset that returns verifiable response types (raw [blocks](../../concepts/glossary/#block) and [CARs](../../concepts/glossary/#car))
+* [Path Gateway](https://specs.ipfs.tech/http-gateways/path-gateway/) ← **START HERE**, other types of gateway are specified as a delta against this specification.
+* [Trustless Gateway](https://specs.ipfs.tech/http-gateways/trustless-gateway/) is a subset that returns verifiable response types (raw [blocks](../../concepts/glossary.md#block) and [CARs](../../concepts/glossary.md#car))
 
 ### Web
 
 Special types of gateway which leverage `Host` header in addition to URL `pathname`. Designed for website hosting and improved interoperability with web browsers and [origin-based security model](https://en.wikipedia.org/wiki/Same-origin_policy).
 
-* [Subdomain Gateway](https://github.com/ipfs/specs/blob/main/http-gateways/SUBDOMAIN_GATEWAY.md)
-* [DNSLink Website Hosting](https://github.com/ipfs/specs/blob/main/http-gateways/DNSLINK_GATEWAY.md)
+* [Subdomain Gateway](https://specs.ipfs.tech/http-gateways/subdomain-gateway/)
+* [DNSLink Website Hosting](https://specs.ipfs.tech/http-gateways/dnslink-gateway/)
 
 ::: tip
 
-If you are a gateway operator or an implementer, consider joining [Gateway Operators Forum](https://discuss.ipfs.tech/c/31)
+If you are a gateway operator or an implementer, consider testing with [gateway-conformance](https://github.com/ipfs/gateway-conformance) test suite.
 
 :::