Misc docs improvements #3953

cloutiertyler · 2026-01-06T16:19:23Z

Description of Changes

This PR does several small things:

It removes the explicit h1 tags on every page, and either uses the side bar title directly, or puts it in the frontmatter
It merges what are currently called quickstarts into a single Chat App Tutorial
It creates new quickstarts which just use spacetime dev --template to get you up and running quickly
It adds a "The Zen of SpacetimeDB" page much like the Zen of Python which goes over the 5 key principles of SpacetimeDB
It reorders all Tabs groups so that the ordering is TypeScript, C#, Rust, Unreal, C++, Blueprints (order of decreasing popularity).
It improves the sidebar navigation by having categories act as overview pages, and also fixes the breadcrumbs
It fixes various small typos and issues
Closes Misleading Cursor instruction for non-windows users #3610 and adds cursor rules files generally
It fixes general styling on the docs page by bring it inline with the UI design:

Old:

New:

Screen.Recording.2026-01-08.at.11.23.22.PM.mov

API and ABI breaking changes

This PR does NOT change any old links. It does add new pages though.

Expected complexity level and risk

3 - it's a large change. I manually tested the TypeScript Chat App Tutorial but I have not gone through the Rust and C# quickstarts. However, we have testing on the quickstarts and this is text only so can be carefully reviewed.

Testing

Ran through each step of the Chat App TypeScript tutorial to ensure it is working
Ran and tested the styles and the functionality of the side bar

- Fix incorrect client labels in key-architecture.md: - Changed "Rust client" to "TypeScript client" in TypeScript tab - Changed "A Unreal" to "An Unreal" for grammar - Changed "Unreal C++" to "Unreal Blueprint" in Blueprint tab - Remove trailing spaces from quickstart titles (C# and Rust) - Fix malformed PostgreSQL wire protocol link in pg-wire.md

Major reorganization of the getting started documentation: - Rename "Intro" section to "Getting Started" - Create new short quickstarts for each framework: - React, Unity, Unreal, TypeScript, Rust, C# - Each focuses on `spacetime dev --template <name>` - Merge previous chat app "quickstarts" into single tutorial: - New unified chat-app.md with language tabs - Combines TypeScript, C#, and Rust examples - Remove old separate language quickstart files The quickstarts are now concise (~50 lines) getting-started guides, while detailed tutorials provide comprehensive walkthroughs.

Structural fixes: - Fix duplicate numbering: rename 00300-using-auth-claims.md to 00350 - Fix placeholder labels: "Blackholio" -> "Unity/Unreal Tutorial" - Standardize numbering: rename 01000-reference to 00200-reference - Rename tables/overview.md to tables.md for consistency New content: - Add Core Concepts landing page with section overview - Add Developer Resources landing page with section overview These changes improve navigation consistency and provide better entry points into major documentation sections.

Content additions: - Add "Zen of SpacetimeDB" article explaining the philosophy: - Everything is a table - Everything is persistent - Everything is real-time - Everything is transactional - Everything is programmable - Add practical ChatGPT/OpenAI API example to procedures docs showing how to integrate with external APIs Fixes: - Remove smart contracts comparison from what-is-spacetimedb - Fix title capitalization in procedures.md (Title -> title)

- Add concrete benefits (hot-swap, persistence guarantees) - Clarify transactional atomicity - Emphasize programmability and Turing completeness - Add memorable taglines throughout

Forward the template parameter to spacetime init, allowing users to create projects from templates directly via `spacetime dev --template`. Also adds integration tests for the template flag functionality.

docs/docs/00100-intro/00100-getting-started/00400-key-architecture.md

- react → basic-react - typescript → basic-typescript - rust → basic-rust - csharp → basic-c-sharp - Remove unity and unreal quickstarts (no templates exist yet)

All three language tests (Rust, C#, TypeScript) now reference the unified 00100-chat-app.md which contains code blocks for all languages.

The merged tutorial was missing the complete Rust and C# client code that existed in the original separate quickstart files. The smoke tests require this code to work. Added: - Complete Rust client tutorial (~500 lines, 15 code blocks) - Complete C# client tutorial (~550 lines, 18 code blocks) This ensures the smoke tests can extract complete, compilable client code when concatenating all code blocks.

The TypeScript React tab was missing the full client tutorial that existed in the original quickstart. Added: - Complete React app structure (App.tsx, App.css, index.css) - SpacetimeDB React hooks (useTable, useReducer, useSpacetimeDB) - Full connection setup with callbacks - Event subscription examples (onInsert, onDelete) Tutorial is now 2494 lines with all original content preserved.

Remove explicit doc IDs from quickstart files to let Docusaurus auto-generate them from the file path, matching what QuickstartLinks.tsx expects. Also restore C# slug to /quickstarts/c-sharp.

On macOS, localhost can resolve to both 127.0.0.1 (IPv4) and ::1 (IPv6). If another service uses the same port on one address family, browsers may connect to the wrong service depending on which address they try first. This change checks port availability on both IPv4 and IPv6 before binding. If the port is in use, the user is prompted to use the next available port. A --non-interactive flag is added to skip the prompt and fail immediately.

Guide users through testing the completed app: - Send first message - Set username and see retroactive updates - Test multiplayer with multiple windows - Watch online/offline status changes - Test persistence by restarting Also includes earlier fixes for directory structure (root instead of client/) and instruction ordering.

Move AI rules from docs/.cursor/rules/ to docs/static/ai-rules/ and embed them in the CLI binary. When users run spacetime init, the AI rules are copied to their project's .cursor/rules/ directory. This helps AI coding assistants understand SpacetimeDB conventions.

The section is specific to the web client UI, so it belongs inside that tab rather than after all tabs.

Add DbConnection to the imports and add a note explaining why it's imported from module_bindings (it's a generated type with table info).

- Restructure sidebar with static section headers (INTRO, CORE CONCEPTS, etc.) using HTML items instead of collapsible categories - Flatten Getting Started items directly under INTRO section - Add Ask AI Chat as direct doc link with star icon - Add right-aligned chevrons that rotate on expand/collapse - Update heading spacing (h2: 48px, h3: 32px, h4: 24px top margins) - Add paragraph spacing (24px bottom margin) - Update hover color to full #E6E9F0 - Demote tutorial tab headings to h3/h4 to reduce TOC clutter - Add toc_max_heading_level: 2 to chat-app tutorial

- Change markdown body links from green to neutral gray (#B6C0CF) - Add underline decoration to links per Figma design - Increase navbar right items spacing from 24px to 32px

- Remove language-specific install headers (Install .NET 8, Install Rust) - Add margin-top to tabs elements for better visual separation

…ture.md Signed-off-by: Tyler Cloutier <[email protected]>

- Move category index docs outside their directories (like Convex pattern) so clicking a category label navigates to its overview page without showing a duplicate child item - Style active category state to extend full width including chevron - Use Docusaurus .menu__caret button for chevron instead of ::after - Fix broken links in index pages and csharp-reference - Balance caret padding for visual alignment

Create Steps component with StepByStep, Step, StepText, and StepCode exports for structured quickstart guides. CSS uses counters for automatic step numbering with a two-column grid layout (description left, code right). Also adds max-width to InstallCardLink.

- Remove H1 headings from all docs (Docusaurus auto-generates from frontmatter title) - Add sidebar_label for quickstarts to show short names in sidebar while keeping descriptive page titles - Restructure Unity/Unreal tutorials: rename overview.md to index.md so clicking category goes directly to overview content - Add links to Quickstarts and Tutorials categories to enable chevrons

Reorder language tabs based on developer population popularity. Order is now: TypeScript, C#, Rust, then Unreal variants.

cloutiertyler · 2026-01-09T00:27:37Z

/update-llm-benchmark

clockwork-labs-bot · 2026-01-09T00:57:40Z

LLM Benchmark Results (ci-quickfix)

Language	Mode	Category	Tests Passed	Pass %	Task Pass %
Rust	rustdoc_json	basics	20/27	74.1%	75.0%
Rust	rustdoc_json	schema	23/34	67.6%	60.0%
Rust	rustdoc_json	total	43/61	70.5%	68.2%
C#	docs	basics	27/27	100.0%	100.0%
C#	docs	schema	24/34	70.6%	70.0%
C#	docs	total	51/61	83.6%	86.4%

_{Generated at: 2026-01-09T02:40:12.086Z}

- Rename developing-databases.md to spacetime-dev.md - Rename building-publishing.md to spacetime-publish.md - Move transactions-atomicity.md to come first in order - Add custom breadcrumb styling: chevron separator, home icon, active page color

cloutiertyler · 2026-01-09T02:10:03Z

/update-llm-benchmark

jdetter · 2026-01-09T15:45:06Z

crates/cli/src/subcommands/dev.rs

+            if resolved_server == "local" {
+                init_argv.push("--local");
+            }
+            let template = args.get_one::<String>("template");


If the user passes a template via --template and the project already exists, should we print an error or warning that --template is being ignored?

jdetter

I don't have any blocking review on this as a codeowner, just some optional improvements. I also have not tested this.

jdetter · 2026-01-09T16:14:10Z

crates/standalone/src/subcommands/start.rs

+/// and the actual bind will fail with a clear error if it happens.
+fn is_port_available(port: u16) -> bool {
+    let ipv4_addr = SocketAddr::from(([127, 0, 0, 1], port));
+    let ipv6_addr = SocketAddr::V6(SocketAddrV6::new(Ipv6Addr::LOCALHOST, port, 0, 0));


optional nit: Here you're only checking the port on specifically the 127.0.0.1 address which likely could cause this to check pass when it should fail. Many services bind to a specific interface (eth0, enp0s1, etc.) and do not run on localhost so this check would fail to find those services. I think this should also pass in the requested interface IP as well and we should check that in addition to checking the localhost interface. This is especially important if the user passes 0.0.0.0 as their requested interface.

If we don't do this you would just get whatever error you get when you try to bind to the port on that specific interface, which should also hopefully give a reasonable error.

Also, this only scopes on IPv4 not IPv6.

cloutiertyler added 6 commits January 6, 2026 11:03

Update Zen of SpacetimeDB with stronger principles

ad5cc1f

- Add concrete benefits (hot-swap, persistence guarantees) - Clarify transactional atomicity - Emphasize programmability and Turing completeness - Add memorable taglines throughout

Add --template flag to spacetime dev command

a97f3fd

Forward the template parameter to spacetime init, allowing users to create projects from templates directly via `spacetime dev --template`. Also adds integration tests for the template flag functionality.

cloutiertyler commented Jan 7, 2026

View reviewed changes

docs/docs/00100-intro/00100-getting-started/00400-key-architecture.md Outdated Show resolved Hide resolved

cloutiertyler commented Jan 7, 2026

View reviewed changes

docs/docs/00100-intro/00100-getting-started/00400-key-architecture.md Outdated Show resolved Hide resolved

cloutiertyler changed the title ~~This is what Claude suggests~~ Misc docs improvements Jan 7, 2026

cloutiertyler and others added 20 commits January 6, 2026 22:52

Fix quickstart template names to match templates-list.json

163ebe2

- react → basic-react - typescript → basic-typescript - rust → basic-rust - csharp → basic-c-sharp - Remove unity and unreal quickstarts (no templates exist yet)

Update smoke test paths to use merged chat-app tutorial

a71817a

All three language tests (Rust, C#, TypeScript) now reference the unified 00100-chat-app.md which contains code blocks for all languages.

Fix QuickstartLinks to use new doc IDs

6fc9855

Restore original doc IDs and slugs for quickstarts

ffee7bc

Remove explicit doc IDs from quickstart files to let Docusaurus auto-generate them from the file path, matching what QuickstartLinks.tsx expects. Also restore C# slug to /quickstarts/c-sharp.

Remove accidentally committed SPACETIME_PROGRAMMING_STANDARDS.md

53a7bb4

Rename csharp.md to c-sharp.md to match expected doc ID

16ec28a

Tell it to leave strict mode along in .mdc

af8669d

Cargo fmt

53c4724

Move 'Try it out!' section inside TypeScript React tab

d11802f

The section is specific to the web client UI, so it belongs inside that tab rather than after all tabs.

Fix missing DbConnection import in tutorial

15f416e

Add DbConnection to the imports and add a note explaining why it's imported from module_bindings (it's a generated type with table info).

Demote 'Creating the Client' heading from h1 to h2

daac08a

Update link styling and navbar spacing

8dd3859

- Change markdown body links from green to neutral gray (#B6C0CF) - Add underline decoration to links per Figma design - Increase navbar right items spacing from 24px to 32px

Clean up chat app tutorial and add tabs spacing

2bbf501

- Remove language-specific install headers (Install .NET 8, Install Rust) - Add margin-top to tabs elements for better visual separation

Merge branch 'master' into tyler/claude-docs

6f6ff2a

cloutiertyler requested a review from aasoni January 8, 2026 03:10

cloutiertyler added 2 commits January 8, 2026 01:46

Update docs/docs/00100-intro/00100-getting-started/00400-key-architec…

6dfd4c4

…ture.md Signed-off-by: Tyler Cloutier <[email protected]>

Update docs/docs/00100-intro/00100-getting-started/00400-key-architec…

91242a5

…ture.md Signed-off-by: Tyler Cloutier <[email protected]>

aasoni mentioned this pull request Jan 8, 2026

Create Vue framework sdk #3975

Open

cloutiertyler and others added 7 commits January 8, 2026 11:10

Fix clippy manual_strip lint in strip_mdc_frontmatter

4c2fb5f

Small fixes

9851d9f

Reorder tabs to TypeScript, C#, Rust

66ea1f3

Reorder language tabs based on developer population popularity. Order is now: TypeScript, C#, Rust, then Unreal variants.

Merge branch 'master' into tyler/claude-docs

b90aacd

cloutiertyler marked this pull request as ready for review January 9, 2026 00:01

cloutiertyler requested review from bfops and jdetter as code owners January 9, 2026 00:01

cloutiertyler added 2 commits January 8, 2026 19:15

Fix CLI docs generator path after docs restructure

cd1ed30

Regenerate CLI docs

2560551

Fix JSX img paths to include baseUrl

1185726

cloutiertyler added 2 commits January 8, 2026 20:15

Minor change

6dda61b

cloutiertyler enabled auto-merge January 9, 2026 02:13

spacetimedb-bot and others added 2 commits January 9, 2026 02:40

Update LLM benchmark results

619a887

Fixed styling to be just so for the nav bar

8a2e077

jdetter reviewed Jan 9, 2026

View reviewed changes

jdetter approved these changes Jan 9, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Misc docs improvements #3953

Misc docs improvements #3953

cloutiertyler commented Jan 6, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

cloutiertyler commented Jan 9, 2026

Uh oh!

clockwork-labs-bot commented Jan 9, 2026 •

edited

Loading

Uh oh!

cloutiertyler commented Jan 9, 2026

Uh oh!

jdetter Jan 9, 2026

Uh oh!

jdetter left a comment

Uh oh!

jdetter Jan 9, 2026

Uh oh!

egormanga Jan 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Misc docs improvements #3953

Are you sure you want to change the base?

Misc docs improvements #3953

Conversation

cloutiertyler commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of Changes

API and ABI breaking changes

Expected complexity level and risk

Testing

Uh oh!

Uh oh!

Uh oh!

cloutiertyler commented Jan 9, 2026

Uh oh!

clockwork-labs-bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

LLM Benchmark Results (ci-quickfix)

Uh oh!

cloutiertyler commented Jan 9, 2026

Uh oh!

jdetter Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

jdetter left a comment

Choose a reason for hiding this comment

Uh oh!

jdetter Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

egormanga Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

cloutiertyler commented Jan 6, 2026 •

edited

Loading

clockwork-labs-bot commented Jan 9, 2026 •

edited

Loading