First pass at reorganizing the docs and making them nice (#3494)

# Description of Changes

This PR is the first in a series of PRs which are an effort the
reorganize the docs and make it easier for people to get started using
SpacetimeDB.

This PR:

1. Renames all folders to be `kebab-case`. This is because `docIds` are
set based on folder and file names, and there is no way to override that
within a file (all you can change with `id: my-id` is the last component
of the id. Because we want to be able to access docs in react components
we need stable predictable ids.
- This also necessitates setting up a few `_category_.json` files so
that the categories do not show up as kebab case in the sidebar.
2. Adds a few React components with images so it's clearer on how to get
started
3. Reorganizes the quickstarts to be at the top of the side bar and
simplifies the server and client into a single document named for the
language
4. Sets up redirections so the old links to the old documents now point
to the new documents
5. Copies the entirety of `typography.css` from the website into this
repo for the purpose of keeping them identical
6. Makes minor fixes and improvements to the contents of the docs

In a future PR, I intend to:

1. Add a tutorial section to the docs which will include two tutorials:
Blackholio and Chat
2. Turn the chat quickstart documents into the Chat tutorial and
consolidate it into a single file with different language switchers (if
this is feasible)
3. Create a new quickstart section, which has a quickstart guide for
each platform that we support so far, namely:
    - Vanilla TypeScript
    - Vanilla JavaScript
    - Vanilla Rust
    - Vanilla C#
    - React
    - Unity
    - Unreal
4. Update the quickstart guides to do the following (in the future I
will add more platforms with this scheme):
- Use `spacetime dev --template <framework-template>` to create a new
project for the given framework
    - Insert data into the database
    - Add a new `reducer` to the template
    - Add a new `table` to the template
    - Add a new `view` to the template
    - Call the reducer from the client
    - Subscribe to the `view` from the template
5. Break up the current per language module reference files into files
about SpacetimeDB concepts with a `TabGroup` for each language, namely:
    - Modules
    - Tables
    - Reducers
    - Procedures
    - Code generation
    - DbConnection (and the SDK API)
    - Auth
    - etc.
The idea being that we should explain our platform by concept, not by
language. This will also allow us to reuse a lot of prose that is
repeated in the different language documents.

# API and ABI breaking changes

None

# Expected complexity level and risk

1

# Testing

- [x] Tested the documents locally to ensure that they render properly

---------

Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>

Author: cloutiertyler

docs/docs/00-Ask AI/01-ask-ai.mdx renamed to docs/docs/00-ask-ai/01-ask-ai.mdx

@@ -1,20 +1,30 @@
 ---
 title: Overview
+id: overview
 slug: /
 ---
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
+import { InstallCardLink } from "@site/src/components/InstallCardLink";
+import { CardLink } from "@site/src/components/CardLink";
+import { CardLinkGrid } from "@site/src/components/CardLinkGrid";
+import { QuickstartLinks } from "@site/src/components/QuickstartLinks";
+import DocsList from "@site/src/components/DocsList";
 
 # SpacetimeDB Documentation
 
 ## Installation
 
-You can run SpacetimeDB as a standalone database server via the `spacetime` CLI tool.
+You can get started by first installing the `spacetime` CLI tool. The `spacetime` CLI tool makes it extremely easy to manage your databases and deployments.
 
-You can find the instructions to install the CLI tool for your platform [here](https://spacetimedb.com/install).
+<InstallCardLink />
 
-To get started running your own standalone instance of SpacetimeDB check out our [Getting Started Guide](/getting-started).
+## Quickstart Guides
+
+Choose your favorite language and follow one of our quickstart guides to get started building your first app with SpacetimeDB.
+
+<QuickstartLinks /> 
 
 ## What is SpacetimeDB?
 
@@ -82,20 +92,20 @@ You write SQL queries specifying what information a client is interested in -- f
 
 Every SpacetimeDB database contains a collection of [stored procedures](https://en.wikipedia.org/wiki/Stored_procedure) and schema definitions. Such a collection is called a **module**, which can be written in C# or Rust. They specify a database schema and the business logic that responds to client requests. Modules are administered using the `spacetime` CLI tool.
 
-- [Rust](/modules/rust) - [(Quickstart)](/modules/rust/quickstart)
-- [C#](/modules/c-sharp) - [(Quickstart)](/modules/c-sharp/quickstart)
+- [Rust](/modules/rust) - [(Quickstart)](/docs/quickstarts/rust)
+- [C#](/modules/c-sharp) - [(Quickstart)](/docs/quickstarts/c-sharp)
 
 ### Client-side SDKs
 
 **Clients** are applications that connect to SpacetimeDB databases. The `spacetime` CLI tool supports automatically generating interface code that makes it easy to interact with a particular database.
 
-- [Rust](/sdks/rust) - [(Quickstart)](/sdks/rust/quickstart)
-- [C#](/sdks/c-sharp) - [(Quickstart)](/sdks/c-sharp/quickstart)
-- [TypeScript](/sdks/typescript) - [(Quickstart)](/sdks/typescript/quickstart)
+- [Rust](/sdks/rust) - [(Quickstart)](/docs/quickstarts/rust)
+- [C#](/sdks/c-sharp) - [(Quickstart)](/docs/quickstarts/c-sharp)
+- [TypeScript](/sdks/typescript) - [(Quickstart)](/docs/quickstarts/typescript)
 
 ### Unity
 
-SpacetimeDB was designed first and foremost as the backend for multiplayer Unity games. To learn more about using SpacetimeDB with Unity, jump on over to the [SpacetimeDB Unity Tutorial](/unity/part-1).
+SpacetimeDB was designed first and foremost as the backend for multiplayer Unity games. To learn more about using SpacetimeDB with Unity, jump on over to the [SpacetimeDB Unity Tutorial](/docs/tutorials/unity/part-1).
 
 ## Key architectural concepts
 
@@ -111,7 +121,7 @@ A database exports [tables](#table), which store data, and [reducers](#reducer),
 
 A database's schema and business logic is specified by a piece of software called a **module**. Modules can be written in C# or Rust.
 
-(Technically, a SpacetimeDB module is a [WebAssembly module](https://developer.mozilla.org/en-US/docs/WebAssembly) that imports a specific low-level [WebAssembly ABI](/webassembly-abi) and exports a small number of special functions. However, the SpacetimeDB [server-side libraries](#module-libraries) hide these low-level details. As a developer, writing a module is mostly like writing any other C# or Rust application, except for the fact that a [special CLI tool](https://spacetimedb.com/install) is used to deploy the application.)
+(Technically, a SpacetimeDB module is a [WebAssembly module](https://developer.mozilla.org/en-US/docs/WebAssembly) that imports a specific low-level [WebAssembly ABI](/webassembly-abi) and exports a small number of special functions. However, the SpacetimeDB [server-side libraries](#module-libraries) hide these low-level details. As a developer, writing a module is mostly like writing any other C# or Rust application, except for the fact that a [special CLI tool](pathname:///install) is used to deploy the application.)
 
 ### Table
 
@@ -346,4 +356,4 @@ A user has a single [`Identity`](#identity), but may open multiple connections t
    Follow our [Quick Start](/getting-started) guide!
 
 1. How do I create a Unity game with SpacetimeDB?
-   Follow our [Unity Tutorial](/unity) guide!
+   Follow our [Unity Tutorial](/docs/tutorials/unity) guide!

docs/docs/00-Ask AI/_category_.json renamed to docs/docs/00-ask-ai/_category_.json

@@ -5,7 +5,7 @@ slug: /getting-started
 
 To develop SpacetimeDB databases locally, you will need to run the Standalone version of the server.
 
-1. [Install](https://spacetimedb.com/install) the SpacetimeDB CLI (Command Line Interface)
+1. [Install](pathname:///install) the SpacetimeDB CLI (Command Line Interface)
 2. Run the start command:
 
 ```bash
@@ -33,14 +33,14 @@ You are now ready to start developing SpacetimeDB modules. See below for a quick
 
 ### Server (Module)
 
-- [Rust](/modules/rust/quickstart)
-- [C#](/modules/c-sharp/quickstart)
+- [Rust](/docs/quickstarts/rust)
+- [C#](/docs/quickstarts/c-sharp)
 
 ⚡**Note:** Rust is [roughly 2x faster](https://faun.dev/c/links/faun/c-vs-rust-vs-go-a-performance-benchmarking-in-kubernetes/) than C#
 
 ### Client
 
-- [Rust](/sdks/rust/quickstart)
-- [C# (Standalone)](/sdks/c-sharp/quickstart)
-- [C# (Unity)](/unity/part-1)
-- [Typescript](/sdks/typescript/quickstart)
+- [Rust](/docs/quickstarts/rust)
+- [C# (Standalone)](/docs/quickstarts/c-sharp)
+- [C# (Unity)](/docs/tutorials/unity/part-1)
+- [Typescript](/docs/quickstarts/typescript)

docs/docs/01-Intro/01-overview.md renamed to docs/docs/01-intro/01-overview.md

@@ -1,22 +1,256 @@
 ---
-title: TypeScript Quickstart
-slug: /sdks/typescript/quickstart
+title: TypeScript 
+slug: /quickstarts/typescript
+id: typescript
 ---
 
-# TypeScript Client SDK Quickstart
+import { InstallCardLink } from "@site/src/components/InstallCardLink";
 
-In this guide, you'll learn how to use TypeScript to create a SpacetimeDB client application.
+# Quickstart Chat App
 
-Please note that TypeScript is supported as a client language only. **Before you get started on this guide**, you should complete one of the quickstart guides for creating a SpacetimeDB server module listed below.
+In this tutorial, we'll implement a simple chat server as a SpacetimeDB **TypeScript** module.
 
-- [Rust](/modules/rust/quickstart)
-- [C#](/modules/c-sharp/quickstart)
+A SpacetimeDB module is code that gets bundled to a single JavaScript artifact and uploaded to SpacetimeDB. This code becomes server-side logic that interfaces directly with SpacetimeDB’s relational database.
 
-By the end of this introduction, you will have created a basic single page web app which connects to the `quickstart-chat` database created in the above module quickstart guides.
+Each SpacetimeDB module defines a set of **tables** and a set of **reducers**.
+
+- Tables are declared with `table({ ...opts }, { ...columns })`. Each inserted object is a row; each field is a column.
+- Tables are **private** by default (readable only by the owner and your module code). Set `{ public: true }` to make them readable by everyone; writes still happen only via reducers.
+- A **reducer** is a function that reads/writes the database. Each reducer runs in its own transaction; its writes commit only if it completes without throwing. In TypeScript, reducers are registered with `spacetimedb.reducer(name, argTypes, handler)` and throw `new SenderError("...")` for user-visible errors.
+
+:::note
+SpacetimeDB runs your module inside the database host (not Node.js). There’s no direct filesystem or network access from reducers.
+:::
+
+## Install SpacetimeDB
+
+If you haven’t already, start by [installing SpacetimeDB](pathname:///install). This installs the `spacetime` CLI used to build, publish, and interact with your database.
+
+<InstallCardLink />
+
+## Project structure
+
+Let's start by running `spacetime init` to initialize our project's directory structure:
+
+```bash
+spacetime init --lang typescript quickstart-chat
+```
+
+`spacetime init` will ask you for a project path in which to put your project. By default this will be `./quickstart-chat`. This basic project will have a few helper files like Cursor rules for SpacetimeDB and a `spacetimedb` directory which is where your SpacetimeDB module code will go.
+
+Inside the `spacetimedb/` directory will be a `src/index.ts` entrypoint (required for publishing).
+
+## Declare imports
+
+Open `spacetimedb/src/index.ts`. Replace its contents with the following imports to start building a bare-bones real-time chat server:
+
+```ts server
+import { schema, t, table, SenderError } from 'spacetimedb/server';
+```
+
+From `spacetimedb/server`, we import:
+
+- `table` to define SpacetimeDB tables.
+- `t` for column/type builders.
+- `schema` to compose our database schema and register reducers.
+- `SenderError` to signal user-visible (transaction-aborting) errors.
+
+## Define tables
+
+We’ll store two kinds of data: information about each user, and the messages that have been sent.
+
+For each `User`, we’ll store their `identity` (the caller’s unique identifier), an optional display `name`, and whether they’re currently `online`. We’ll use `identity` as the primary key (unique and indexed).
+
+Add to `spacetimedb/src/index.ts`:
+
+```ts server
+const User = table(
+  { name: 'user', public: true },
+  {
+    identity: t.identity().primaryKey(),
+    name: t.string().optional(),
+    online: t.bool(),
+  }
+);
+
+const Message = table(
+  { name: 'message', public: true },
+  {
+    sender: t.identity(),
+    sent: t.timestamp(),
+    text: t.string(),
+  }
+);
+
+// Compose the schema (gives us ctx.db.user and ctx.db.message, etc.)
+const spacetimedb = schema(User, Message);
+```
+
+## Set users’ names
+
+We’ll allow users to set a display name, since raw identities aren’t user-friendly. Define a reducer `set_name` that validates input, looks up the caller’s `User` row by primary key, and updates it. If there’s no user row (e.g., the caller invoked via CLI without a connection and hasn’t connected before), we’ll return an error.
+
+Add:
+
+```ts server
+function validateName(name: string) {
+  if (!name) {
+    throw new SenderError('Names must not be empty');
+  }
+}
+
+spacetimedb.reducer('set_name', { name: t.string() }, (ctx, { name }) => {
+  validateName(name);
+  const user = ctx.db.user.identity.find(ctx.sender);
+  if (!user) {
+    throw new SenderError('Cannot set name for unknown user');
+  }
+  ctx.db.user.identity.update({ ...user, name });
+});
+```
+
+You can extend `validateName` with moderation checks, Unicode normalization, printable-character filtering, max length checks, or duplicate-name rejection.
+
+## Send messages
+
+Define a reducer `send_message` to insert a new `Message` with the caller’s identity and the call timestamp. As with names, we’ll validate that text isn’t empty.
+
+Add:
+
+```ts server
+function validateMessage(text: string) {
+  if (!text) {
+    throw new SenderError('Messages must not be empty');
+  }
+}
+
+spacetimedb.reducer('send_message', { text: t.string() }, (ctx, { text }) => {
+  validateMessage(text);
+  console.info(`User ${ctx.sender}: ${text}`);
+  ctx.db.message.insert({
+    sender: ctx.sender,
+    text,
+    sent: ctx.timestamp,
+  });
+});
+```
+
+Possible extensions:
+
+- Reject messages from users who haven’t set a name.
+- Rate-limit messages per user.
+
+## Set users’ online status
+
+SpacetimeDB can invoke lifecycle reducers when clients connect/disconnect. We’ll create or update a `User` row to mark the caller online on connect, and mark them offline on disconnect.
+
+Add:
+
+```ts server
+// Called once when the module bundle is installed / updated.
+// We'll keep it empty for this quickstart.
+spacetimedb.init(_ctx => {});
+
+spacetimedb.clientConnected(ctx => {
+  const user = ctx.db.user.identity.find(ctx.sender);
+  if (user) {
+    // Returning user: set online=true, keep identity/name.
+    ctx.db.user.identity.update({ ...user, online: true });
+  } else {
+    // New user: create a User row with no name yet.
+    ctx.db.user.insert({
+      identity: ctx.sender,
+      name: undefined,
+      online: true,
+    });
+  }
+});
+
+spacetimedb.clientDisconnected(ctx => {
+  const user = ctx.db.user.identity.find(ctx.sender);
+  if (user) {
+    ctx.db.user.identity.update({ ...user, online: false });
+  } else {
+    // Shouldn't happen (disconnect without prior connect)
+    console.warn(
+      `Disconnect event for unknown user with identity ${ctx.sender}`
+    );
+  }
+});
+```
+
+## Start the server
+
+If you haven’t already started the SpacetimeDB host on your machine, run this in a **separate terminal** and leave it running:
+
+```bash
+spacetime start
+```
+
+(If it’s already running, you can skip this step.)
+
+## Publish the module
+
+From the `quickstart-chat` directory (the parent of `spacetimedb/`):
+
+```bash
+spacetime publish --server local --project-path spacetimedb quickstart-chat
+```
+
+You can choose any unique, URL-safe database name in place of `quickstart-chat`. The CLI will show the database **Identity** (a hex string) as well; you can use either the name or identity with CLI commands.
+
+## Call reducers
+
+Use the CLI to call reducers. Arguments are passed as JSON (strings may be given bare for single string parameters).
+
+Send a message:
+
+```bash
+spacetime call --server local quickstart-chat send_message "Hello, World!"
+```
+
+Check that it ran by viewing logs (owner-only):
+
+```bash
+spacetime logs --server local quickstart-chat
+```
+
+You should see output similar to:
+
+```text
+<timestamp>  INFO: spacetimedb: Creating table `message`
+<timestamp>  INFO: spacetimedb: Creating table `user`
+<timestamp>  INFO: spacetimedb: Database initialized
+<timestamp>  INFO: console: User 0x...: Hello, World!
+```
+
+## SQL queries
+
+SpacetimeDB supports a subset of SQL so you can query your data:
+
+```bash
+spacetime sql --server local quickstart-chat "SELECT * FROM message"
+```
+
+Output will resemble:
+
+```text
+ sender                                                             | sent                             | text
+--------------------------------------------------------------------+----------------------------------+-----------------
+ 0x93dda09db9a56d8fa6c024d843e805d8262191db3b4ba84c5efcd1ad451fed4e | 2025-04-08T15:47:46.935402+00:00 | "Hello, World!"
+```
+
+You've just set up your first TypeScript module in SpacetimeDB! You can find the full code for this client [TypeScript server module example](https://github.com/clockworklabs/SpacetimeDB/tree/master/modules/quickstart-chat-ts).
+
+# Creating the client
+
+Next, you'll learn how to use TypeScript to create a SpacetimeDB client application.
+
+By the end of this introduction, you will have created a basic single page web app which connects to the `quickstart-chat` database you just created.
 
 ## Project structure
 
-Enter the directory `quickstart-chat` you created in the [Rust Module Quickstart](/modules/rust/quickstart) or [C# Module Quickstart](/modules/c-sharp/quickstart) guides:
+Enter the directory `quickstart-chat` you created in the [Rust Module Quickstart](/docs/quickstarts/rust) or [C# Module Quickstart](/docs/quickstarts/c-sharp) guides:
 
 ```bash
 cd quickstart-chat
@@ -467,7 +701,7 @@ spacetime generate --lang typescript --out-dir client/src/module_bindings --proj
 
 :::note
 
-This command assumes you've already created a server module in `quickstart-chat/server`. If you haven't completed one of the server module quickstart guides, you can follow either the [Rust](/modules/rust/quickstart) or [C#](/modules/c-sharp/quickstart) module quickstart to create one and then return here.
+This command assumes you've already created a server module in `quickstart-chat/server`. If you haven't completed one of the server module quickstart guides, you can follow either the [Rust](/docs/quickstarts/rust) or [C#](/docs/quickstarts/c-sharp) module quickstart to create one and then return here.
 
 :::