ContextQMD
Back to Sui

Sui Documentation

docs/README.md

latest7.9 KB
Original Source

Sui Documentation

This directory contains the assets required to build and update the Sui documentation. The directory is split between content and site.

For AI agents and LLMs

If you are an AI agent, coding assistant, or LLM parsing this repository, start here.

llms.txt

The Sui documentation build generates an llms.txt file at https://docs.sui.io/llms.txt. Use it as your entry point for understanding the documentation structure and locating specific topics.

Style guide skill file

A condensed, machine-readable version of the Sui Documentation Style Guide is available as a skill file at SUI_STYLE_GUIDE_SKILL.md. This file contains all style rules from the full style guide in a format optimized for agent ingestion. Use it when writing or revising any documentation for this repository.

Repository layout for documentation

docs/
├── content/              # All documentation source files (.mdx)
│   ├── concepts/         # Sui architecture, objects, transactions, cryptography
│   ├── guides/           # Developer guides, tutorials, app examples
│   ├── references/       # API references, framework docs, CLI reference, contribution guides
│   ├── standards/        # Sui standards (Closed-Loop Token, DeepBook, Kiosk, Wallet)
│   └── sidebars.js       # Navigation structure / page hierarchy
├── site/                 # Docusaurus site configuration, plugins, and build output
│   ├── src/              # Custom components, plugins, utilities
│   ├── docusaurus.config.js
├── snippets/             # Reusable code snippets referenced by ImportContent

Key files for agents

  • docs/content/sidebars.js: Defines the full navigation tree. Parse this to understand page hierarchy and relationships.
  • docs/SUI_STYLE_GUIDE_SKILL.md: Condensed style guide rules. Ingest before writing or editing documentation.
  • docs/content/references/contribute/style-guide.mdx: The full human-readable style guide source.
  • docs/content/references/contribute/mdx-components.mdx: Reference for all custom MDX components and Docusaurus plugins.

What not to edit

Several sections are auto-generated during the build and must not be edited directly:

  • Framework reference (/references/framework): Generated from cargo-doc Markdown in /sui/crates.
  • GraphQL reference (/references/sui-api/sui-graphql): Generated from the GraphQL schema.
  • OpenRPC and gRPC specifications: Downloaded during build by utility scripts.

Documentation content conventions

  • All documentation pages are .mdx files with YAML frontmatter (title, description, keywords).
  • Pages use Docusaurus admonitions (:::info, :::tip, :::caution, :::danger) for callouts.
  • Code samples should be sourced from GitHub using the <ImportContent> component when possible, rather than copied inline. See the MDX Components page for component reference.
  • Every sidebar category must have a corresponding index.mdx page using link.type: 'doc'

Build the site locally

To run docs.sui.io locally, open the site directory in a terminal or console. Use a package manager to install the required modules:

shell
pnpm install

Full build

Run a full build to generate all required assets and compile the static site:

shell
pnpm build

A full build is necessary after a fresh clone because it downloads specification files and generates content that the site depends on. The build script performs the following steps before compiling:

  1. Generates the import context (generate-import-context.js).
  2. Downloads gRPC specification files (grpc-download.js).
  3. Generates GraphQL reference documentation (graphql-to-doc), then removes entries without descriptions.
  4. Downloads OpenRPC specification files (getopenrpcspecs.js).
  5. Post-processes GraphQL output (massagegraphql.js).
  6. Runs docusaurus build to compile the static site into site/build.
  7. Copies Markdown files and generates llms.txt for LLM consumption.
  8. Runs internal link checking against the content directory.

The build fails on errors like bad internal links or missing imports, and displays the cause of the error in the console.

If you get an error about missing open-rpc specs when running the site locally, run pnpm build first. It downloads and prepares the required files.

Development preview

After a successful build, use the following command to start a development preview at localhost:3000:

shell
pnpm start

The development server watches for changes to files in the content directory and site source files, and updates the UI to match any saves you make. The development preview ignores some errors (like broken internal links) to provide a faster feedback loop.

Run pnpm build again before submitting your changes for review, as the full build catches errors that the development preview does not.

Auto-generated content

Several sections of the documentation are auto-generated during the build and should not be edited directly.

Framework reference (/references/framework): Generated by the framework plugin, which imports cargo-doc Markdown from /sui/crates and transforms it into documentation pages. The build script removes this directory before each build and regenerates it from source. See the components documentation for details.

GraphQL reference (/references/sui-api/sui-graphql): Generated by the graphql-to-doc Docusaurus plugin, then cleaned by remove-no-desc.mjs. These pages are generated from the GraphQL schema and should not be manually edited.

OpenRPC and gRPC specifications: Downloaded during the build by utility scripts in src/utils/.

Pull requests

Sui uses Vercel to host its documentation site. Vercel builds a preview of the documentation for every pull request submitted to the Sui repo. You can find a link to this preview in the PR comment section from the Vercel bot. Click the Visit Preview link for the sui-core project to verify your changes behave as you expect.

To view the Vercel preview before your changes are ready for review, mark your PR as a draft.

Style guide

All documentation contributions must follow the Sui Documentation Style Guide. A machine-readable version is available in SKILL.md at the root of this directory. Key requirements include:

  • Use US English spelling and active voice.
  • Use second person ("you") instead of first or third person.
  • Use present tense. Avoid future tense unless describing a scheduled event.
  • Do not use Latin abbreviations (for example, use "for example" instead of "e.g.").
  • Use serial (Oxford) commas.
  • Capitalize product names and proper nouns consistently. See the style guide for the full terminology list.
  • Use sentence case for section headings.

Components and plugins

The Sui documentation uses shared components from the ML Shared Docusaurus repo and Sui-specific components. For a complete reference of all custom components and plugins, see the MDX Components page.

Contributing

License

The Sui documentation is distributed under the CC BY 4.0 license.