chore: many fixes

License: MIT
Signed-off-by: Oli Evans <[email protected]>

src/pages/_meta.json

@@ -1,6 +1,6 @@
 {
   "docs": {
-    "title": "🏠",
+    "title": "Docs",
     "type": "page"
   }
 }

src/pages/docs/_meta.json

@@ -1,6 +1,8 @@
 {
-  "index": "Start",
+  "index": "Welcome",
+  "quickstart": "Quickstart",
+  "how-tos": "How to",
+  "concepts": "Concepts",
   "w3cli": "Command line",
-  "w3up-client": "JS Client",
-  "concepts": "Concepts"
+  "w3up-client": "JS Client"
 }

src/pages/docs/concepts/_meta.json

@@ -1,5 +1,15 @@
 {
-  "ucan": "UCAN",
-  "did": "DID",
-  "car": "CAR"
+  "ucans-and-web3storage": "UCANs and web3.storage",
+  "content-addressing": "Content-addressing",
+  "upload-vs-store": "Upload vs. Store",
+  "architecture-options": "Architecture options",
+  "car": "Content Archive (CAR) files",
+  "filecoin-storage": "Filecoin",
+  "ipfs-gateways": "IPFS Gateways",
+  "did": {
+    "display": "hidden"
+  },
+  "ucan": {
+    "display": "hidden"
+  }
 }

src/pages/docs/concepts/architecture-options.md

@@ -1,12 +1,10 @@
 # Architecture options
 
-Possible architectures of using web3.storage to upload
-
 UCAN opens up a number of options in how to integrate with w3up: Should you, the developer, own the Space? Should you delegate permissions to your users? Or should your user own their own Space? Broadly, there are three ways to integrate:
 
 - Client-server: You (the developer) own the Space, and your user uploads to your backend infra before you upload it to the service
 - Delegated: You own the Space, but you give a delegated UCAN token to your user's Agent to upload directly to the service (rather than needing to touch the upload in your backend)
-- (Most complex) User-owned: Your user owns the Space and registers it and they use it to upload directly with the service; if you want to instrument visibility into what they're uploading, you'll have to write separate code in your app for it
+- User-owned: Your user owns the Space and registers it and they use it to upload directly with the service; if you want to instrument visibility into what they're uploading, you'll have to write separate code in your app for it
 
 In the How-tos section of the docs, we focused on the first two options, as they are the most familiar today. However, you can implement each of these in a number of ways, but we talk through some considerations when implementing a given option.
 

src/pages/docs/concepts/content-addressing.md

@@ -1,24 +1,22 @@
-## Content addressing
-
-Content addressing in brief
+# Content addressing
 
 web3.storage's decentralized file storage relies on _content addressing_ to find, reference, and retrieve your files on the network. Content addressing is a technique for organizing and locating data in a system in which the key used to locate content is derived from the content itself, rather than its location. While you don't need to understand content addressing to be able to incorporate web3.storage in your apps and services, if you're curious about what's going on under the hood, read on.
 
-### [The basic problem](https://web3.storage/docs/concepts/content-addressing/#the-basic-problem)
+## The basic problem
 
 Consider what happens when you resolve a link like web3.storage/docs/concepts/content-addressing. First, your operating system queries a global shared key-value store, split into many domains — you may know this as the Domain Name System (DNS). The DNS returns an IP address that your network card can use to send HTTP requests over the network, where this site's naming conventions turn the key /concepts/content-addressing into a response payload.
 
 The problem is, components of an address like web3.storage/docs/concepts/content-addressing are _mutable_, meaning they can change over time. In the context of the web, where _everything_ is mutable and dynamic, this is just the way it's always been. As a result, [link rot](https://en.wikipedia-on-ipfs.org/wiki/Link_rot) is just something we've all learned to live with.
 
-### [CIDs: Location-independent, globally unique keys](https://web3.storage/docs/concepts/content-addressing/#cids-location-independent-globally-unique-keys)
+## CIDs: Location-independent, globally unique keys
 
 However, thanks to content addressing, link rot may become a thing of the past. A content-addressed system such as web3.storage is like our key-value-based DNS, with one significant difference: You no longer get to choose the keys. Instead, the keys are derived directly from the file contents using an algorithm that will always generate the same key for the same content.
 
 As a result, we no longer need to coordinate among multiple writers to our store by splitting the key space into domains and locations on file systems. There's now one universal domain: the domain of all possible values. If multiple people add the same value, there's no collision in the key space. They just each get the same key back from the put method, with one additional benefit: The availability and performance of retrievals on the network is increased. This gives our keys _location independence_. There's one other important result: Each individual key is a unique signature for the data itself, ensuring _verifiability_ that the key matches the content and the content hasn't been altered.
 
 This type of key is called a _content identifier (CID)_. Once you know the CID of a file on the web3.storage network, you have all you need for the network to locate and return the file back to you.
 
-[web3.storage CIDs under the hood](https://web3.storage/docs/concepts/content-addressing/#web3storage-cids-under-the-hood)
+## web3.storage CIDs under the hood
 
 web3.storage uses CIDs to make its decentralized file storage work, with help from [IPFS](https://ipfs.io/) for locating files and making sure they're always available.
 
@@ -33,14 +31,14 @@ There are two types of CIDs that web3.storage interacts with:
 
 In the vast majority of cases, users should focus on content CIDs, as this is what they'll be using to fetch their content. If you stick with using the recommended client and CLI methods, then you won't really have to ever worry about the shard CIDs.
 
-### [Summary](https://web3.storage/docs/concepts/content-addressing/#summary)
+## Summary
 
 Using content addressing for locating files rather than the legacy web's method of location-dependent addressing responds to several critical weaknesses of the legacy web:
 
 - Content addressing solves for the problem behind link rot — the mutability of location-dependent storage systems — by using a hashing algorithm to generate a unique CID for each file that can be used as the lookup key for a file rather than a URL.
 - In addition to making sure files don't get lost if they're moved, content addressing also ensures that users intending to retrieve a specific version of a file will be guaranteed to retrieve that version for as long as it exists anywhere on the network.
 
-### [Learn more](https://web3.storage/docs/concepts/content-addressing/#learn-more)
+## Learn more
 
 Want a deep dive into content addressing, how it works, and why it's important? Check out [ProtoSchool](https://proto.school/content-addressing/) for an in-depth look at content addressing on the decentralized web, plus a wealth of other interactive tutorials on DWeb concepts, protocols, and tools.
 

src/pages/docs/concepts/filecoin-storage.md

@@ -1,8 +1,8 @@
-## Filecoin storage
+# Filecoin storage
 
-### Filecoin storage
+The Filecoin network is a great building block for any decentralized storage system. Independent storage providers periodically must cryptographically prove that they are physically storing your specific data for a specific duration of time. When they submit these proofs to the network, other nodes verify these proofs, and this is what ends up on the Filecoin blockchain. So, anyone at any given moment can trustlessly verify that specific content is persisted, the number of copies on the network, and with who they are stored with. 
 
-The Filecoin network is a great building block for any decentralized storage system. Independent storage providers periodically must cryptographically prove that they are physically storing your specific data for a specific duration of time. When they submit these proofs to the network, other nodes verify these proofs, and this is what ends up on the Filecoin blockchain. So, anyone at any given moment can trustlessly verify that specific content is persisted, the number of copies on the network, and with who they are stored with. Read more about Filecoin proofs [here](https://filecoin.io/blog/posts/what-sets-us-apart-filecoin-s-proof-system/).
+Read more about Filecoin proofs [here](https://filecoin.io/blog/posts/what-sets-us-apart-filecoin-s-proof-system/).
 
 Because of the open nature of the Filecoin network allowing anyone to participate, it's very inexpensive to store data on the Filecoin network. As a result, web3.storage uses the network today to back up all its data on the decentralized web. In the future, we will launch new products that allow users to take advantage of Filecoin for "colder," disruptively expensive data storage.
 

src/pages/docs/concepts/ipfs-gateways.md

@@ -1,6 +1,4 @@
-## IPFS Gateways
-
-### IPFS HTTP Gateways
+# IPFS Gateways
 
 web3.storage uses the [InterPlanetary File System (IPFS)](https://ipfs.io/) as a key part of its storage and retrieval infrastructure.
 
@@ -12,15 +10,15 @@ As more browsers like [Brave](https://brave.com/ipfs-support/) and [Opera](https
 
 For more information about fetching content that you uploaded through an IPFS HTTP gateway, see the Retrieve section.
 
-## [Types of gateway](https://web3.storage/docs/concepts/w3link/#types-of-gateway)
+## Types of gateway
 
 The official [IPFS documentation on gateways](https://docs.ipfs.io/concepts/ipfs-gateway/) is helpful for understanding the types of gateways in the IPFS ecosystem and how they're used.
 
 One of the key things to understand for our purposes is the different [resolution styles](https://docs.ipfs.io/concepts/ipfs-gateway/#resolution-style) that can be used to fetch content using gateway URLs.
 
 If you check the [list of public gateways](https://ipfs.github.io/public-gateway-checker/), you'll see that some support "subdomain" style URLs, while others only support path-style URLs. Below is a short refresher on the distinction between the two styles.
 
-### [Path style URLs](https://web3.storage/docs/concepts/w3link/#path-style-urls)
+### Path style URLs
 
 A "path style" URL puts the IPFS CID into the path portion of the gateway URL, like this:
 
@@ -30,7 +28,7 @@ If the CID points to a directory listing, you can append the name of a file with
 
 [https://w3s.link/ipfs/bafybeid4gwmvbza257a7rx52bheeplwlaogshu4rgse3eaudfkfm7tx2my/hi-gateway.txt](https://w3s.link/ipfs/bafybeid4gwmvbza257a7rx52bheeplwlaogshu4rgse3eaudfkfm7tx2my/hi-gateway.txt)
 
-### [Subdomain style URLs](https://web3.storage/docs/concepts/w3link/#subdomain-style-urls)
+### Subdomain style URLs
 
 A "subdomain style" gateway URL puts the CID into the host portion of the URL, as a subdomain of the gateway host, like this: