feat: docs in website!

merge the docs repo into the website at /docs.

doing this at deploy time proved tricky, so now we just build all the things together.

markdown files can be added directly to `src/pages/docs/your-topic-here.md` and add it to a `_meta.json` at the same level to set it's link title and position in the nav.

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

src/globals.css

@@ -0,0 +1,57 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer utilities {
+  .bg-grad {
+    background-color: rgb(244 244 245);
+    background-image: linear-gradient(225deg, #ff149296 0%, #00ffff96 100%);
+    background-size: 400% 400%;
+    animation: bgPosDrift 60s ease infinite;
+  }
+  .text-grad {
+    background: linear-gradient(92deg, #B507DC 0.82%, #2F0FDB 26.77%);
+    background-clip: text;
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+  }
+  .one-corn {
+    border-bottom-right-radius: 100% 100px;
+  }
+  .one-corn-top {
+    border-top-right-radius: 100% 100px;
+  }
+}
+
+/* make the header bright */
+/* .nextra-nav-container .nextra-nav-container-blur {
+  background-color: transparent !important;
+}
+:is(html[class~="dark"] .nextra-nav-container .nextra-nav-container-blur) {
+  background-color: transparent !important;
+} */
+.nextra-nav-container.nx-bg-transparent {
+  @apply bg-grad
+}
+
+/* Line numbers for code examples */
+code {
+  counter-reset: step;
+  counter-increment: step 0;
+}
+
+code .line::before {
+  content: counter(step);
+  counter-increment: step;
+  width: 1rem;
+  margin-right: 1.5rem;
+  display: inline-block;
+  text-align: right;
+  color: rgba(115,138,148,.4)
+}
+
+@keyframes bgPosDrift {
+  0% { background-position: 0% 50%; }
+  50% { background-position: 100% 50%; }
+  100% { background-position: 0% 50%; }
+}

src/pages/_app.js

@@ -0,0 +1,5 @@
+import '../globals.css'
+
+export default function MyApp({ Component, pageProps }) {
+  return <Component {...pageProps} />
+}

src/pages/_meta.json

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

src/pages/docs/_meta.json

@@ -0,0 +1,6 @@
+{
+  "index": "Start",
+  "w3cli": "Command line",
+  "w3up-client": "JS Client",
+  "concepts": "Concepts"
+}

src/pages/docs/concepts/_meta.json

@@ -0,0 +1,4 @@
+{
+  "ucan": "UCAN",
+  "did": "DID"
+}

src/pages/docs/concepts/did.md

@@ -0,0 +1,3 @@
+
+
+TODO: explain what DIDs are and how we use them

src/pages/docs/glossary.yml

@@ -0,0 +1,189 @@
+
+- id: agent
+  name: Agent
+  definition: A software component that manages signing keys and delegations needed to invoke w3up APIs.
+  details: |
+    Agents are used to invoke capabilities provided by the w3up service layer, using the [ucanto](https://github.com/web3-storage/ucanto) RPC framework. 
+    
+    Agents are created locally on an end-user's device, and users are encouraged to create new agents for each device (or browser) that they want to use, rather than sharing agent keys between devices.
+
+- id: audience
+  name: Audience
+  definition: The intended recipient of a UCAN token, identified by DID
+  details: |
+    Each UCAN token is "addressed to" a specific principal, known as the audience.
+    
+    When invoking a capability, the service provider is the audience of the invocation.
+   
+    When delegating permissions, the audience is the party receiving the delegation.
+
+- id: bitswap
+  definition: A peer-to-peer protocol used by IPFS and Filecoin to distribute blocks of data throughout the network.
+  details: |
+    While the w3up APIs do not use Bitswap directly, once data is stored with web3.storage it is made available via Bitswap to the larger IPFS network.
+
+- id: block
+  definition: A chunk of binary data that can be identified by CID.
+  details: |
+    Data stored with web3.storage is encoded into blocks, with large files consisting of several blocks linked together.
+
+    Blocks can be uniquely identified by <Term id="cid">CID (Content Identifier)</Term>, and are often bundled into Content Archives (CARs) for transport and storage.
+
+- id: car
+  name: CAR
+  definition: A collection of blocks, packaged for storage and transport.
+  details: |
+    CARs are like a [tar file](https://en.wikipedia.org/wiki/Tar_(computing)) for content-addressed data. 
+    
+    Used extensively by w3up protocols, although most users shoudn't be exposed to them directly for the most common operations.
+
+- id: cid
+  name: CID
+  definition: A Content Identifier that uniquely and verifiably identifies a block of data.
+  details: |
+    A CID consists of a cryptographic hash of the data it identifies, as well as a few bytes of metadata indicating what format the content is expected to be in. 
+    
+    See [the IPFS docs](https://docs.ipfs.tech/concepts/content-addressing/) for more details.
+
+- id: dag
+  name: DAG
+  definition: A Directed Acyclic Graph data structure.
+  details: |
+    A Directed Acyclic Graph (DAG) is a data structure that represents a collection of linked objects ("nodes"), 
+    where the links between nodes ("edges") have certain properties. 
+    For example, you can't have "cycles" or loops in the graph, where following a set of edges brings you back to the node you started from.
+
+    IPFS encodes files and directories into DAGs comprised of <Term id="block">blocks</Term> of data,
+    where each block can optionally link to other blocks using its <Term id="cid">CID</Term>.
+
+    Most DAGs will have a single "root" node which represents the "top" of the graph. 
+    By starting at the root node and traversing the links, you can find all the blocks that make up the DAG.
+
+- id: did
+  name: DID
+  definition: A decentralized identifier that contains or links to a cryptographic public key.
+  details: |
+    DIDs are decentralized identifiers that don't rely on any single authority to issue and validate.
+
+    See our [DID intro article](/concepts/dids/) for more details.
+
+- id: dht
+  name: DHT
+  definition: A Distributed Hash Table allows many peers in a peer-to-peer network to locate each other and coordinate to provide services.
+  details: |
+    IPFS uses a DHT to advertise content to the network, making it discoverable to all peers who query the DHT.
+    The DHT does not contain the full content - instead a small "provider record" contains addresses of peers 
+    who will serve the content on request (e.g. via <Term id="bitswap">Bitswap</Term>).
+    
+    Content stored with web3.storage is discoverable via the public IPFS DHT.
+
+- id: elastic-ipfs
+  name: Elastic IPFS
+  definition: A "cloud-native" IPFS implementation developed by Protocol Labs.
+  details: |
+    Elastic IPFS is an implementation of IPFS designed to leverage cloud storage for scalability and efficient retrieval.
+
+    Content is stored on commodity cloud storage (e.g. Amazon S3, Cloudflare R2) in <Term id="car">CAR</Term> format,
+    along with indexes that allow efficient location and retrieval of data within the CARs.
+    
+    Elastic IPFS interoperates with the public IPFS network by making content available via <Term id="bitswap">Bitswap</Term>.
+
+- id: gateway
+  name: Gateway
+  definition: An IPFS gateway allows retrieving IPFS content via HTTP, allowing any web browser to access data stored with IPFS.
+  details: |
+    Gateways act as a "bridge" between IPFS's peer-to-peer protocols and the HTTP protocol used by web browsers.
+
+    You can fetch IPFS content from a gateway by creating a gateway URL from the <Term id="cid">CID</Term> of your content,
+
+    To use the web3.storage gateway at `w3s.link`, make a URL like this, replacing `${cid}` with the CID you want to link to:
+
+    ```
+    https://${cid}.ipfs.w3s.link
+    ```
+
+- id: ipfs
+  name: IPFS
+  definition: The InterPlanetary File System, a distributed system for sharing and linking to content-addressed data.
+  details: |
+    IPFS is a system for organizing, locating, and transmitting data using cryptographic hashes to identify each piece of content.
+    There are many IPFS implementations, which work together to form a public network
+    (as well as specialized private networks).
+    web3.storage makes all uploaded content available to the IPFS network
+    via <Term id="bitswap">Bitswap</Term>, as well as via HTTP through <Term id="gateway">gateways</Term>.
+
+- id: ipld
+  name: IPLD
+  definition: InterPlanetary Linked Data is a collection of data formats that can be linked together by CID.
+  details: |
+    IPLD is a specification for data types that can be linked together by <Term id="cid">CID</Term> to form a <Term id="dag">DAG</Term>.
+
+    <Term id="unixfs">UnixFS</Term> is an IPLD data format, but IPLD also supports
+    JSON, CBOR, and other encodings for structured data that do not need the "file-like"
+    metadata included in UnixFS.
+
+    See the [IPLD website](https://ipld.io) for more information.
+
+- id: issuer
+  name: Issuer
+  definition: The creator and signer of a UCAN token, identified by DID.
+  details: |
+    Each UCAN token must be signed by the private key belonging to the issuer.
+   
+    When invoking a capability, the issuer is the agent executing the invocation.
+   
+    When delegating permissions, the issuer is the agent who currently possesses 
+    the given permissions and is delegating them to another agent (the audience).
+
+- id: space
+  definition: A unique identifier that acts as a "namespace" for uploaded content.
+  details: |
+    The w3up APIs use "spaces" to group uploads together, similar to how cloud storage buckets group stored objects.
+
+    Spaces act as the "destination" for uploaded data, and permissions to write to and/or manage a space can be delegated
+    to multiple <Term id="agent">agents</Term>.
+
+- id: ucan
+  name: UCAN
+  definition: User Controlled Authorization Networks are an authentication and authorization protocol designed for decentralized systems.
+  details: |
+    The w3up APIs use UCAN extensively to provide services and authorize invocations.
+
+    See our [intro to UCAN article](/concepts/ucan/) for an overview.
+
+- id: ucanto
+  name: ucanto
+  definition: A remote procedure call (RPC) framework based on UCANs.
+  details: |
+    The <Term id="ucan">UCAN</Term>-based w3up APIs are implemented using the [ucanto framework](https://github.com/web3.storage/ucanto).
+    
+    ucanto provides the "plumbing" for type-safe UCAN-based APIs, allowing services to define capability handlers which can be invoked by authorized clients.
+
+- id: unixfs
+  name: UnixFS
+  definition: A data format used by IPFS to represent files and directories.
+  details: |
+    UnixFS is a data format used by <Term id="ipfs">IPFS</Term> to encode files and directories into a <Term id="dag">DAG</Term> structure.
+    When preparing data for IPFS, the UnixFS encoder will chunk files into <Term id="block">blocks</Term> that are linked by <Term id="cid">CID</Term>. 
+
+    UnixFS is used by IPFS on all operating systems, including Windows.
+    The name indicates that the format supports some common metadata used on Unix platforms,
+    for example, symbolic links and modification time.
+
+- id: w3up
+  name: w3up
+  definition: The name of web3.storage's UCAN-based storage platform.
+  details: |
+    When web3.storage first launched, it offered a traditional "RESTful" / "JSON over HTTP" API,
+    aimed at getting traditional web developers tapped into the potential of decentralized,
+    content addressed storage.
+
+    After learning a lot from our first iteration, we created a new API backed
+    by <Term id="elastic-ipfs">Elastic IPFS</Term> that leverages <Term id="ucan">UCANs</Term> 
+    to provide secure and flexible authorization that can integrate with traditional web apps
+    as well as fully decentralized smart contract applications.
+
+    The new APIs are provided by a collection of <Term id="ucanto">ucanto</Term> services and are
+    collectively known as "w3up" to distinguish them from our "v1" RESTful API.
+
+    You can learn more about the motivations for w3up in our [beta announcement blog post](https://blog.web3.storage/posts/w3up-beta-launch).

src/pages/docs/index.mdx

@@ -0,0 +1,15 @@
+import { Cards, Card } from 'nextra/components'
+import { Callout } from 'nextra/components'
+
+**Under the hood, web3.storage is backed by the provable storage of [IPFS](https://ipfs.io) and [Filecoin](https://filecoin.io).**
+
+When it comes down to building your next application, service, or website, web3.storage keeps it simple. You get all the benefits of decentralized storage technologies with the frictionless experience you expect in a modern dev workflow. **All you need to use web3.storage is an account and your data.** 
+
+Building a **JavaScript** or **TypeScript** app? see our [guide to using w3up-client](./w3up-client.md).
+
+Feeling terminal? Use the [w3cli](./w3cli.md) command!.
+
+<Cards>
+  <Card icon='💾 ' title="CLI" href="./w3cli" />
+  <Card icon='✨ ' title="JS Client" href="./w3up-client" />
+</Cards>

src/pages/docs/w3cli.md

@@ -0,0 +1,83 @@
+# `w3cli`
+
+You can get started using web3.storage right away from your command line using `w3`, our command line interface tool.
+
+In this guide, we'll walk through the following steps:
+
+1. [Installing the `w3` tool](#install)
+2. [Creating and registering your first space](#create-your-first-space)
+3. [Uploading a file or directory](#upload-files)
+4. [Viewing your file with IPFS](#view-your-file-with-ipfs)
+
+## Install
+
+You'll need [Node](https://nodejs.com) version 18 or higher, with NPM version 7 or higher to complete this guide.
+You can check your local versions like this
+
+```bash
+node --version && npm --version
+```
+
+Install the `@web3-storage/w3cli` package with `npm`
+
+```bash
+npm install -g @web3-storage/w3cli
+```
+
+Once the install is complete, you'll have a `w3` command available. Try running `w3 --help` to get an idea of what's possible.
+
+## Create your first space
+
+When you upload things to web3.storage, each upload is associated with a <abbr id="space">"space,"</abbr> which is a unique identifier that acts as a namespace for your content.
+
+Spaces are identified by <abbr id="did">DID</abbr> using keys created locally on your devices. To use a space for uploads, it needs to be registered with the storage service by providing an email address.
+
+To create a space using the `w3` command line tool, use the `w3 space create` command. You can optionally give your space a "friendly" name, which acts like an alias for the space's DID and can make it easier to tell your spaces apart. In the example below, we'll use the name `Documents`:
+
+```bash
+w3 space create Documents
+```
+
+The DID for the new space will be printed to the console. It should look something like this, although the part after `did:key` will be unique to your space:
+
+```
+did:key:z6MkixXechJLc3TWibQj9RN6AiFx8VoMY9HNB3Y97WcwK3fm
+```
+
+You can now run `w3 spaces ls` to show a list of your spaces:
+
+```bash
+* did:key:z6MkixXechJLc3TWibQj9RN6AiFx8VoMY9HNB3Y97WcwK3fm Documents
+```
+
+The `*` symbol indicates that the `Documents` space is currently active. If you make multiple spaces, you can switch between them with `w3 space use`, passing in the name or DID of the space you want to activate.
+
+Before you can upload, you'll need to register the new space with the web3.storage service using `w3 space register`:
+
+```bash
+w3 space register [email protected]
+```
+
+This command will wait for you to check your email and click the confirmation link that was sent to your address. Once you confirm your email, you'll see a success message and are ready to upload.
+
+## Upload files
+
+Now that you've [created and registered a space](#create-space), you're ready to upload files to web3.storage!
+
+Use the `w3 up` command to upload a file or directory:
+
+```bash
+w3 up your-file.txt
+```
+
+Once your upload is complete, you should see a URL that links to your file on the `w3s.link` <abbr id="gateway">IPFS gateway</abbr>.
+
+If you uploaded a single file, the link will resolve to an IPFS directory listing, with the actual file contained in the directory. This "wrapper" directory preserves the original filename of your upload, which can help organize your content and allows people to download files using their original names. If you don't want to create the wrapper directory, you can pass in the `--no-wrap` flag when running `w3 up`.
+
+When uploading directories, files beginning with a `.` character are ignored by default. To include hidden files instead, pass in the `-H` or `--hidden` flag.
+
+## View your file with IPFS
+
+When your upload completes, you should see a link to your files on the `w3s.link` <abbr id="gateway">IPFS gateway</abbr>. Just click the link to see your files!
+
+[concepts-did]: ../concepts/dids.md