Docusaurus migration by JulienLavocat · Pull Request #3343 · clockworklabs/SpacetimeDB

JulienLavocat · 2025-10-03T10:04:02Z

Description of Changes

Migrate the documentation site to Docusaurus.
Add a GitHub Action workflow that runs pnpm build on pull requests targeting master.
This command checks for broken links and images and ensures the site builds correctly.
Add a GitHub Action workflow to publish the docs automatically when a merge occurs on the docs/release branch.

Important: The workflows haven't been tested yet due to the fact that they need to be merged first before being able to run. It's a fairly basic workflow I don't expect this to block anyone but anyways I will make another PR with the complete changes when I can actually run it.

API and ABI Breaking Changes

No breaking changes for SpacetimeDB users.
Documentation contributors should experience minimal disruption — content is still written in Markdown.

Expected Complexity Level and Risk

Complexity: 3/5

Reasons:

Several adjustments were made to fit Docusaurus conventions:
- Replaced our custom :::server-rust blocks with Docusaurus <Tabs/> components.
- Converted “Note” callouts using admonitions instead of Markdown blockquotes.
- Updated all images (including Unity tutorial ones, which were previously commented out).
- Moved images from the DO bucket into the repository at docs/static/images.
Customized Docusaurus CSS and one component to apply our theme and color palette.

Testing

Tested locally.

Review Notes

This PR involves many file changes — a full code review is likely not productive.
Instead, please focus on verifying that the documentation content was migrated correctly:

Review sections you’re familiar with to confirm accuracy.
Ensure formatting, links, and images render as expected.

You can follow the updated README for instructions on running Docusaurus locally.

.github/workflows/docs-publish.yaml

.github/workflows/docs-test.yaml

jdetter

One question on this one so far, otherwise the rest of the edits look good to me

.github/workflows/docs-publish.yaml

docs/src/theme/NavbarItem/NavbarNavLink.tsx

JasonAtClockwork · 2025-10-08T16:03:09Z

I've reviewed the entire Unreal tutorial and it looks 100% (all links, code and images), the only thing is it looks like new version is missing the Unreal Reference from the Client SDK:

New:

Old:

jdetter

Reminder that I still needed to run this command in order to get the docs rendering:

pnpm add @docusaurus/theme-common

jdetter

I've reviewed a majority of the documentation and I think it looks good. There are just 2 issues to fix here I think:

Fix the issue with having to manually install @docusaurus/theme-common
Fix the code formatting issues in the Unity tutorial

besides that I think this is ready to go. Let me know when you want me to take another look 👍

docs/docs/03-Unity Tutorial/04-part-3.md

JulienLavocat · 2025-10-10T09:35:54Z

the only thing is it looks like new version is missing the Unreal Reference from the Client SDK:
Added @JasonAtClockwork

JasonAtClockwork · 2025-10-10T15:10:10Z

the only thing is it looks like new version is missing the Unreal Reference from the Client SDK:
Added @JasonAtClockwork

Looks great! All the Unreal stuff is complete.

jdetter

Few more formatting issues here

docs/docs/unity/part-3.md

docs/docs/03-Unity Tutorial/04-part-3.md

Signed-off-by: Julien Lavocat <JulienLavocat@users.noreply.github.com>

Removed the S3 upload step from the docs workflow. Signed-off-by: Julien Lavocat <JulienLavocat@users.noreply.github.com>

JasonAtClockwork

The Unreal work looks great!

Somehow (apparently after #3494) we wound up with a bunch of duplicate folders in our repo, both the old title-case names and the new lower-case names. All of the remaining files in the title-case directories have their last change in #3343, well before #3494, so I don't believe we're losing any intermediate changes by deleting them. I'm not sure how this happened, but it seems to be an easy fix.

# Description of Changes Somehow (apparently after #3494) we wound up with a bunch of duplicate folders in our repo, both the old title-case names and the new lower-case names. All of the remaining files in the title-case directories have their last change in #3343, well before #3494, so I don't believe we're losing any intermediate changes by deleting them. I'm not sure how this happened, but it seems to be an easy fix. # API and ABI breaking changes N/a # Expected complexity level and risk 2 - some small possibility that I accidentally deleted an intentional change that got borked by a merge conflict or something. I don't think I did, tho, based on the age of the git blame on the files deleted here. # Testing None

# Description of Changes Add back the instructions for regenerating CLI docs, which were removed in #3343. I also made a script for it. This also fixes the CI checking this file, which was silently broken in the same PR. I have **not** verified that this works in Git Bash in Windows. # API and ABI breaking changes None # Expected complexity level and risk 1 # Testing - [x] CI passes - [x] CI fails if I change the CLI reference - [x] CLI reference looks visually reasonable on a local `pnpm dev` --------- Signed-off-by: Zeke Foppa <196249+bfops@users.noreply.github.com> Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>

JulienLavocat requested a review from cloutiertyler as a code owner October 3, 2025 10:04

JulienLavocat force-pushed the docusaurus-migration branch 2 times, most recently from fbd26f2 to aa7cca6 Compare October 6, 2025 12:01

bfops added release-any To be landed in any release window no runtime change This change does not affect the final binaries labels Oct 6, 2025

github-advanced-security bot found potential problems Oct 7, 2025

View reviewed changes

.github/workflows/docs-publish.yaml Fixed Show fixed Hide fixed

.github/workflows/docs-test.yaml Fixed Show fixed Hide fixed

JulienLavocat force-pushed the docusaurus-migration branch from ae90c28 to 2a7bf53 Compare October 7, 2025 22:41

github-advanced-security bot found potential problems Oct 8, 2025

View reviewed changes

.github/workflows/docs-test.yaml Fixed Show fixed Hide fixed

JulienLavocat force-pushed the docusaurus-migration branch 7 times, most recently from 46c21ab to f590ae0 Compare October 8, 2025 10:30

jdetter reviewed Oct 8, 2025

View reviewed changes

.github/workflows/docs-publish.yaml Outdated Show resolved Hide resolved

JasonAtClockwork reviewed Oct 8, 2025

View reviewed changes

docs/src/theme/NavbarItem/NavbarNavLink.tsx Show resolved Hide resolved

jdetter requested changes Oct 10, 2025

View reviewed changes

docs/docs/03-Unity Tutorial/04-part-3.md Outdated Show resolved Hide resolved

JulienLavocat force-pushed the docusaurus-migration branch 3 times, most recently from 0892495 to 9f04566 Compare October 10, 2025 09:35

JulienLavocat force-pushed the docusaurus-migration branch from baf85ff to b4d4691 Compare October 10, 2025 09:57

jdetter requested changes Oct 10, 2025

View reviewed changes

docs/docs/unity/part-3.md Show resolved Hide resolved

docs/docs/unity/part-3.md Show resolved Hide resolved

docs/docs/03-Unity Tutorial/04-part-3.md Outdated Show resolved Hide resolved

docs/docs/03-Unity Tutorial/04-part-3.md Outdated Show resolved Hide resolved

JulienLavocat mentioned this pull request Oct 15, 2025

Migrate docs to docusaurus #3258

Closed

JulienLavocat force-pushed the docusaurus-migration branch 2 times, most recently from 42faabf to 8050d6b Compare October 15, 2025 09:44

cloutiertyler and others added 20 commits October 24, 2025 15:45

A few styling fixings

7e2d083

Further styling

ab054e4

Styling adjustments

239f7ed

Disable contextual search

adafcb0

target: '_self' for logo

ae1e7bb

Improve docs searchbar styling

782b02a

Add ask ai

03b80f3

Replace docsearch by Inkeep

8380e37

Update API key in docusaurus.config.tsUpdate inkeep api key

b729575

Signed-off-by: Julien Lavocat <JulienLavocat@users.noreply.github.com>

(tmp) Add publish to test

0910075

Signed-off-by: Julien Lavocat <JulienLavocat@users.noreply.github.com>

Add AI chat

0fc9886

font-familiy is now source for sidebar

143440c

New styles for sidebar

28c4c09

Add active and hover

7432978

Ask AI is now regular item + spacing fixes

c1e4bf6

box shadow instead of border

c0eb025

Another box shadow fix

0dff637

Less jank way of doing the ask ai styling and row level security

6668e40

Fix search bar styling

323ab07

Update docs-test.yaml to remove S3 upload step

b75b278

Removed the S3 upload step from the docs workflow. Signed-off-by: Julien Lavocat <JulienLavocat@users.noreply.github.com>

JulienLavocat force-pushed the docusaurus-migration branch from b4da137 to b75b278 Compare October 24, 2025 13:45

JasonAtClockwork approved these changes Oct 24, 2025

View reviewed changes

JulienLavocat added this pull request to the merge queue Oct 24, 2025

Merged via the queue into master with commit afb8c08 Oct 24, 2025
24 of 25 checks passed

gefjon mentioned this pull request Nov 26, 2025

Delete duplicated docs folders #3780

Merged

bfops mentioned this pull request Dec 15, 2025

Fix CLI reference generation #3403

Merged

3 tasks

Conversation

JulienLavocat commented Oct 3, 2025 • edited by cloutiertyler 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

Review Notes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jdetter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

JasonAtClockwork commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jdetter left a comment

Choose a reason for hiding this comment

Uh oh!

jdetter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

JulienLavocat commented Oct 10, 2025

Uh oh!

JasonAtClockwork commented Oct 10, 2025

Uh oh!

jdetter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JasonAtClockwork left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

JulienLavocat commented Oct 3, 2025 •

edited by cloutiertyler

Loading

JasonAtClockwork commented Oct 8, 2025 •

edited

Loading