Skip to content

Conversation

JulienLavocat
Copy link
Contributor

@JulienLavocat JulienLavocat commented Oct 3, 2025

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:

  1. 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.
  2. 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.

@JulienLavocat JulienLavocat force-pushed the docusaurus-migration branch 2 times, most recently from fbd26f2 to aa7cca6 Compare October 6, 2025 12:01
@bfops 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
@JulienLavocat JulienLavocat force-pushed the docusaurus-migration branch 7 times, most recently from 46c21ab to f590ae0 Compare October 8, 2025 10:30
Copy link
Collaborator

@jdetter jdetter left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@JasonAtClockwork
Copy link
Contributor

JasonAtClockwork commented Oct 8, 2025

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:
Image

Old:
Image

Copy link
Collaborator

@jdetter jdetter left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

pnpm add @docusaurus/theme-common

Copy link
Collaborator

@jdetter jdetter left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

  1. Fix the issue with having to manually install @docusaurus/theme-common
  2. 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 👍

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

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

@JasonAtClockwork
Copy link
Contributor

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.

Copy link
Collaborator

@jdetter jdetter left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Few more formatting issues here

@JulienLavocat JulienLavocat force-pushed the docusaurus-migration branch 2 times, most recently from 42faabf to 8050d6b Compare October 15, 2025 09:44
jdetter and others added 8 commits October 22, 2025 14:18
# Description of Changes

This PR fixes small styling issues with the [docusaurus migration
PR](#3343).

Mainly it:

1. Ensures that we only have one single reference to any particular
color definition (`#fefaef`) so that if we change the style guide (see
figma) we can easily update the colors.
2. It removes references to any colors that are not specified in the
style guide
3. It updates font sizes and styling to be one of the pre-defined styles
specified in the style guide
4. Adds the precise fonts specified in the style guide and ensures that
they are preloaded
5. Makes very minor docs changes
6. Implements the tab highlighting for the selected tab (and on hover)

<img width="578" height="372" alt="image"
src="https://github.com/user-attachments/assets/b1d3962b-220b-4df0-aa65-c8d03b2c613c"
/>


After the docusaurus PR merges I would like to do a larger update to
some of the docs content, but I'm keeping that separate.

# API and ABI breaking changes

None

# Expected complexity level and risk

1

# Testing

<!-- Describe any testing you've done, and any testing you'd like your
reviewers to do,
so that you're confident that all the changes work as expected! -->
- [x] Tested styles locally
- [x] Built and ran pnpm run sever to verify that fonts were being
correctly preloaded
@JulienLavocat JulienLavocat force-pushed the docusaurus-migration branch 2 times, most recently from 7a623bb to 48ad0de Compare October 22, 2025 14:31
Copy link
Contributor

@cloutiertyler cloutiertyler left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks good enough to me now. I think we still need to do some updates on the styling, but I think we'll wait to do a full styling pass from Randy

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

no runtime change This change does not affect the final binaries release-any To be landed in any release window

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants