sui-docs

The Sui documentation site, published at docs.sui.io.

Pages live in content/sui. The site that renders them is sites/sui. A large part of the reference material is not written by hand: it is generated at build time from source in other repositories, listed under Generated pages below.

Layout

content/sui/      the pages. Authored and reviewed here
sites/sui/        the Docusaurus site, its plugins and the shared components
sources.json      the repositories the pages quote, under `codeSources`
scripts/          the fetcher shared by every site in this repo
.cache/           fetched source. Gitignored, created on first fetch

Building

cd sites/sui
pnpm install
pnpm build          # prebuild, then scripts/build-and-check.sh
pnpm start          # prestart, then docusaurus start

The build needs Node 24 (engines in sites/sui/package.json) and network access: it clones five source repositories and fetches several specs. Set GITHUB_TOKEN in the build environment to avoid rate limits, and to let generate-skills.mjs read the skills repository.

A scheduled workflow rebuilds the site every hour. Most of the reference material is generated from source in other repositories, and none of them push here, so without that the generated pages would sit at whatever the last push to this repo happened to fetch.

prebuild fetches and converts. build runs scripts/build-and-check.sh, which regenerates the framework and GraphQL references, builds the site, writes the markdown and llms.txt outputs, and then checks links. It greps the Docusaurus log for [ERROR], MDX compilation failed, Missing file for ImportContent and similar, and fails the build on any of them, because Docusaurus exits zero on several of those.

Generated pages

Do not edit the output; change the generator or its source.

Most of these are gitignored. Two are not. sites/sui/src/data/skills.json is generated but tracked, so regenerating it shows up as a diff and a hand edit to it survives until the next build overwrites it. sites/sui/static/display-preview is written during the build but is neither ignored nor tracked, so it appears as untracked files after a local build.

Output	Generated by	From
content/sui/references/framework/**	src/plugins/framework	crates/sui-framework/docs/{bridge,deepbook,std,sui,sui_system} in MystenLabs/sui
content/sui/references/sui-api/sui-graphql/*	docusaurus graphql-to-doc:beta, then remove-no-desc.mjs and massagegraphql.js	the GraphQL schema
content/sui/references/release-notes.mdx	src/shared/js/convert-release-notes.cjs	release-notes in MystenLabs/sui
content/sui/references/awesome-sui.mdx and awesome-sui/	convert-awesome-sui.mjs	docs/subtree/awesome-sui in MystenLabs/sui
content/sui/references/awesome-sui-gaming.mdx and its directory	convert-awesome-sui-gaming.mjs	docs/subtree/awesome-sui-gaming in MystenLabs/sui
content/sui/documentation.json	grpc-download.js	documentation.json in MystenLabs/sui-apis
content/sui/sui-stack/seal/*.mdx	fetch-external-docs.js, then transform-external-docs.js	MystenLabs/seal
content/sui/sui-stack/messaging/*.mdx	the same pair	MystenLabs/sui-stack-messaging
sites/sui/src/data/skills.json	generate-skills.mjs	every SKILL.md in MystenLabs/skills
sites/sui/src/open-spec/<branch>	getopenrpcspecs.js	the OpenRPC spec in MystenLabs/sui, per branch
sites/sui/.generated/ImportContentMap.ts	generate-import-context.js	the ImportContent tags across the pages
sites/sui/.resolved/	generate-resolved-pages.js	the pages
sites/sui/static/display-preview	cloned and built during build	MystenLabs/display-preview
sites/sui/static/llms.txt, llms-full.txt	src/shared/js/generate-llmstxt.mjs	the built site and its sitemap
sites/sui/build/markdown/	copy-markdown-files.js	the built site

A few pages in sui-stack/seal and sui-stack/messaging are hand-written and survive the fetch; .gitignore negations name them.

Quoted code

Pages embed source from other repositories with ImportContent, naming a path with no repository, like crates/sui-indexer-alt-framework/... or examples/rust/.... Those resolve against a checkout fetched into .cache/code by node ../../scripts/fetch-sources.js --code, configured under codeSources in sources.json:

Repository	Paths
MystenLabs/sui	crates, examples, release-notes, docs/subtree
MystenLabs/ts-sdks	packages
MystenLabs/deepbookv3	packages
MystenLabs/sui-apis	documentation.json
playtron-os/playtron-sdk	whole repository

sites/sui/scripts/lib/roots.cjs resolves the two roots this depends on: CONTENT_ROOT for the pages, SOURCE_ROOT for the code they quote. Override either with DOCS_CONTENT_ROOT or DOCS_SOURCE_ROOT. Nothing should compute either by counting ../ from __dirname.

Shared components

sites/sui/src/shared holds the Docusaurus components, plugins and build scripts the Sui Stack docs sites have in common. MystenLabs/ML-shared-docusaurus is where other sites consume them from, and this repo is the source of truth that publishes to it.

Component and plugin names live once, in src/shared/plugin-names.js. Paths go through the @docs alias and roots.cjs rather than being consumer-specific.

Publish with the Publish shared components workflow, or:

node scripts/publish-shared.js --dry-run   # list what would change
node scripts/publish-shared.js             # open a pull request upstream

It opens a pull request and never pushes to master. It needs SHARED_PUBLISH_TOKEN with write access to that repository.

Migration

Phase	What	State
1	Unpin the scripts that assumed the site, the pages and the quoted source share one checkout	done
2	Move docs/content and docs/site here and get the build green	done
3	Cut docs.sui.io over, leave redirects, move CODEOWNERS	not started
4	Other sites, one at a time	not started