docs: sites introduction and troubleshooting docs for IA revision

docs/content/sites/index.mdx

@@ -1,23 +1,51 @@
 ---
 title: Walrus Sites
+description: "Deploy decentralized websites on Walrus."
+keywords: ["walrus", "walrus sites", "decentralized websites", "static sites", "sui", "site-builder", "portal", "suins", "web hosting"]
 ---
 
-{/* https://linear.app/mysten-labs/issue/DOCS-697/sitesindex */}
-
-This tutorial walks you through the steps necessary to publish a Walrus Site. We also provide the
-instructions on how to add a SuiNS name to it for convenient browsing.
+Walrus Sites are decentralized websites built on [Sui](docs.sui.io) and Walrus. Your site's files are stored on Walrus, a decentralized storage network, while a Sui smart contract records ownership and maps each resource path to its content. Anyone can publish a Walrus Site using the [`site-builder` CLI tool](/docs/sites/getting-started/installing-the-site-builder) and browse it through a [portal](/docs/sites/portals/deploy-locally).
 
 <Cards>
-<Card title="Installing the Site Builder" href="/docs/sites/getting-started/installing-the-site-builder">
-Install and setup the Walrus Sites `site-builder` tool for development.
+
+<Card title="Introduction" href="/docs/sites/introduction/">
+Learn what Walrus Sites are, how they work, and the key components that make up a site.
 </Card>
-
-<Card title="Publishing a Walrus Site" href="/docs/sites/getting-started/publishing-your-first-site">
-Publish your first Walrus Site using the `site-builder` tool.
+ 
+<Card title="Getting Started" href="/docs/sites/getting-started/">
+Install the `site-builder` tool and deploy your first Walrus Site.
 </Card>
-
-<Card title="Set a SuiNS Name" href="/docs/sites/custom-domains/setting-a-suins-name">
-Setup SuiNS names for human-readable Walrus Sites domain names and portal browsing.
+ 
+<Card title="Site Configuration" href="/docs/sites/configuration/">
+Configure your site's routing, headers, metadata, and deployment settings using `ws-resources.json` and `sites-config.yaml`.
 </Card>
-
+
+<Card title="Portals" href="/docs/sites/portals/">
+Learn how portals resolve and serve Walrus Sites to browsers, and how to run your own portal locally.
+</Card>
+
+<Card title="Custom Domains" href="/docs/sites/custom-domains/">
+Assign a SuiNS name to your site for a human-readable URL, or bring your own existing domain.
+</Card>
+
+<Card title="Linking" href="/docs/sites/linking/">
+Link to and from Walrus Sites, including how to give individual Sui objects their own dedicated pages.
+</Card>
+
+<Card title="CI/CD" href="/docs/sites/ci-cd">
+Automate deployments to Walrus Sites using GitHub Actions and other CI/CD pipelines.
+</Card>
+
+<Card title="Security" href="/docs/sites/security">
+Understand the security guarantees of Walrus Sites, site isolation, and how to handle sensitive data.
+</Card>
+
+<Card title="Known Restrictions" href="/docs/sites/known-restrictions">
+Review the current limitations of Walrus Sites, including restrictions on dynamic content, redirects, and backend support.
+</Card>
+
+<Card title="Troubleshooting" href="/docs/sites/troubleshooting">
+Find solutions to common issues encountered when publishing or accessing Walrus Sites.
+</Card>
+
 </Cards>

docs/content/sites/introduction/components.mdx

@@ -1,73 +1,105 @@
 ---
-title: Introduction to Walrus Sites
-description: "Introduction to Walrus Sites - decentralized websites using Sui and Walrus for hosting static web content."
-keywords: ["walrus sites", "decentralized websites", "sui blockchain", "static sites", "web hosting", "nft websites", "suins", "site builder", "dapp"]
+title: Walrus Sites Components
+description: "An overview of the main components that make up a Walrus Site: Walrus blob storage, the Sui site object, the site-builder CLI, ws-resources.json, and portals."
+keywords: ["walrus sites", "site-builder", "portal", "ws-resources", "sui object", "walrus blob", "suins", "static sites", "decentralized websites"]
 ---
 
-{/* https://linear.app/mysten-labs/issue/DOCS-662/sitesintroductioncomponents */}
-
-
-*Walrus Sites* are "web"-sites that use Sui and Walrus as their underlying technology. They are a
-prime example of how Walrus can be used to build new and exciting decentralized applications. Anyone
-can build and deploy a Walrus Site and make it accessible to the world! Interestingly, this documentation
-is itself available as a Walrus Site at https://docs.wal.app/docs/sites/introduction/components (if you
-aren't there already).
-
-At a high level, here are some of the most exciting features:
-
-- Publishing a site does not require managing servers or complex configurations; just provide the
-  source files (produced by your favorite web framework), publish them to Walrus Sites using the
-  [`site-builder` tool](/docs/sites/introduction/technical-overview#the-site-builder), and you are done!
-- Sites can be linked to from ordinary Sui objects. This feature enables, for example, creating an
-  NFT collection in which *every single NFT* has a *personalized website dedicated to it*.
-- Walrus Sites are owned by addresses on Sui and can be exchanged, shared, and updated thanks to
-  Sui's flexible programming model. This means, among other things, that Walrus Sites can leverage
-  the [SuiNS](https://suins.io/) naming system to have human-readable names. No more messing around
-  with DNS!
-- Thanks to Walrus's decentralization and extremely high data availability, there is no risk of
-  having your site wiped for any reason.
-- Since they live on Walrus, these sites cannot have a backend in the traditional sense, and can
-  therefore be considered "static" sites. However, the developer can integrate with Sui-compatible
-  wallets and harness Sui's programmability to add backend functionality to Walrus Sites!
-
-## Show me
-
-To give you a very high-level view of how Walrus Sites work, let's look at an example: A simple
-NFT collection on Sui that has a frontend dApp to mint the NFTs hosted on Walrus Sites, and in
-which *each NFT* has a *specific, personalized Walrus Site*.
-
-You can check out the mint page at https://flatland.wal.app/. This site is served to your
-browser through the Walrus Site *portal* https://wal.app. While the portal's operation is
-explained in a [later section](/docs/sites/portals/deploy-locally), consider for now that there can be many portals (hosted
-by whoever wants to have their own, and even on `localhost`). Further, the only function of the
-portal is to retrieve the metadata (from Sui) and the resource files (from Walrus) that constitute
-the site.
-
-If you have a Sui wallet with some SUI, you can try and "mint a new Flatlander" from the site. This
-creates an NFT from the collection and shows you two links: one to the explorer, and one to the
-"Flatlander site". This latter site is a special Walrus Sites page that exists only for that NFT,
-and has special characteristics (the background color, the image, ...) that are based on the
-contents of the NFT.
-
-The URL to this per-NFT site looks something like this:
-`https://flatland.wal.app/0x811285f7bbbaad302e23a3467ed8b8e56324ab31294c27d7392dac649b215716`.
-You'll notice that the domain remains `wal.app`, but the path is a long and random-looking
-string. This string is actually the [hexadecimal](https://simple.wikipedia.org/wiki/Hexadecimal)
-encoding of the object ID of the NFT, which is [0x811285f7b...][flatlander]. This path is unique to
-each NFT and is used to fetch the metadata and resource files for its corresponding page. The page
-is then rendered based on the characteristics of the NFT.
-
-In summary:
-
-- Walrus Sites are served through a portal; in this case, `https://wal.app`. There can be many
-  portals, and anyone can host one.
-- The subdomain on the URL points to a specific object on Sui that allows the browser to fetch and
-  render the site resources. This pointer should be a SuiNS name, such as `flatland` in
-  `https://flatland.wal.app`.
-- It is possible for each path to be mapped to a specific object on Sui that allows the browser to
-  fetch and render a page based on the characteristics of the NFT.
-
-Curious to know how this magic is possible? Read the [technical overview](/docs/sites/introduction/technical-overview)! If you
-just want to get started trying Walrus Sites out, check the [tutorial](/docs/sites).
-
-[flatlander]: https://suiscan.xyz/mainnet/object/0x811285f7bbbaad302e23a3467ed8b8e56324ab31294c27d7392dac649b215716
+A Walrus Site is made up of 4 main components that work together: the site's resource files stored on Walrus, a [Sui object](https://docs.sui.io/guides/developer/objects/object-model) that indexes those resources, the [`site-builder` CLI](/docs/sites/getting-started/installing-the-site-builder) that publishes and updates the site, and a portal that serves the site to browsers.
+
+## Resource files on Walrus
+
+Your site's static assets (HTML, CSS, JavaScript, images, fonts, and so on) are stored as blobs on Walrus. When you deploy a site, the `site-builder` uploads your build directory to Walrus by encoding multiple files into a [single quilt](/docs/system-overview/quilt) to reduce upload cost and improve upload speed.
+
+Each file in the quilt is assigned a `QuiltPatchID`, which the Sui site object uses to locate and retrieve the file later. Because Walrus is a decentralized storage network, there is no single server that can take your content offline.
+
+:::info
+Blobs are stored for a fixed number of epochs. On Mainnet, each epoch lasts 14 days. On Testnet, each epoch lasts 1 day. The maximum storage duration is 53 epochs.
+:::
+
+The trade-off of using quilts is that you cannot update a single file in isolation. If any file in your site changes, the entire quilt is re-uploaded on the next deploy.
+
+## The Sui site object
+
+Each Walrus Site corresponds to a single object on Sui, defined by the Move smart contract in the [`move/walrus_site`](https://github.com/MystenLabs/walrus-sites/tree/main/move/walrus_site) directory of the repository. At its core, a site object is a simple structure:
+
+```move
+struct Site has key, store {
+    id: UID,
+    name: String,
+}
+```
+
+Each resource (file) in the site is attached to this object as a dynamic field of type `Resource`:
+
+```move
+struct Resource has store, drop {
+    path: String,
+    blob_id: u256,
+    // ...headers and other metadata
+}
+```
+
+The `path` field corresponds to the file's URL path (for example, `/index.html`), and `blob_id` is the Walrus identifier for the file's content. Together, the site object and its dynamic fields form an on-chain index that maps every URL path in your site to its content on Walrus.
+
+Because the site object is a standard Sui object, it follows Sui's ownership model. The wallet that deployed the site owns the object and is the only wallet that can update or destroy it. You can also assign a [SuiNS](https://suins.io/) name to the object, giving your site a human-readable domain name.
+
+## The `site-builder` CLI
+
+The `site-builder` is a Rust CLI tool that creates and manages Walrus Sites. It takes your site's build output directory as input and handles uploading files to Walrus and writing the on-chain index to Sui.
+
+The primary command is [`deploy`](/docs/sites/getting-started/using-the-site-builder#deploy), which both publishes new sites and updates existing ones:
+
+```sh
+site-builder deploy --epochs <NUMBER> <DIRECTORY>
+```
+
+When you run `deploy` for the first time, it publishes a new site and writes the resulting Sui object ID to the `object_id` field in `ws-resources.json`. On subsequent runs, `deploy` reads that object ID and updates the existing site instead of creating a new one.
+
+Additionally, the `site-builder` requires a [`sites-config.yaml` configuration file](/docs/sites/getting-started/using-the-site-builder) that specifies the Sui package ID for the Walrus Sites contract and your network context.
+
+## `ws-resources.json`
+
+[`ws-resources.json`](/docs/sites/configuration/site-configuration) is a configuration file you place in your site's root directory. The `site-builder` reads it during deployment and uses it to control how your site is built and served. The file itself is not uploaded to Walrus and is not accessible to visitors.
+
+The file supports the following fields:
+
+- **`object_id`:** The Sui object ID of your deployed site. The `site-builder` writes this automatically after the first deploy. If present, subsequent `deploy` calls update the existing site rather than publishing a new one.
+- [**`headers`:**](/docs/sites/configuration/specifying-http-headers) Custom HTTP response headers for specific resources. Useful for cache control, content type overrides, and security headers.
+- [**`routes`:**](/docs/sites/configuration/setting-up-routing-rules) Client-side routing rules. Use this to support single-page application (SPA) frameworks such as React or Angular, where the app handles routing in the browser. Routes are defined as path patterns mapped to resource paths.
+- [**`metadata`:**](/docs/sites/configuration/adding-metadata) Site metadata such as `site_name`, `description`, `image_url`, `project_url`, and `creator`. This information is stored in the Sui site object and displayed in wallets.
+- **`ignore`:** A list of path patterns to exclude from deployment. Useful for keeping development files or secrets out of the published site.
+
+A minimal example:
+
+```json
+{
+  "object_id": "0x...",
+  "site_name": "My Site",
+  "routes": {
+    "/app/*": "/index.html"
+  },
+  "metadata": {
+    "description": "A site built on Walrus.",
+    "link": "https://example.wal.app"
+  }
+}
+```
+
+:::caution
+Walrus Sites does not support dynamic redirects. Redirect plugins used in frameworks like Docusaurus resolve routes at the server level, which Walrus Sites does not have. Use the `routes` field in `ws-resources.json` to simulate client-side routing instead.
+:::
+
+## Portals
+
+A [portal](/docs/sites/portals/mainnet-testnet) is the service that resolves and serves a Walrus Site to a visitor's browser. When a visitor navigates to a Walrus Site URL, the portal performs the following steps:
+
+1. Resolves the subdomain to a Sui object ID, either through a SuiNS name lookup or by decoding the Base36-encoded object ID directly from the subdomain.
+2. Reads the site object's dynamic fields from Sui to get the resource map.
+3. Fetches the requested resource's blob from Walrus using the `blob_id` from that map.
+4. Returns the blob content to the browser with the appropriate headers.
+
+This process repeats for every resource the browser requests, such as linked CSS files, scripts, and images.
+
+The public Mainnet portal operated by Mysten Labs is available at [https://wal.app](https://wal.app). It serves sites whose Sui objects have a SuiNS name configured. To access a site without a SuiNS name, use the Base36-encoded object ID as the subdomain, or use the `site-builder convert` command to find it.
+
+Anyone can host their own portal. For setup instructions, see [Deploy a Local Portal](/docs/sites/portals/deploy-locally).