Contributing to MatrixOne Documentation

MatrixOne documentation welcomes corrections, examples, and new guides. English and Chinese source pages now live in the same matrixone-doc repository. Follow the Code of Conduct and use Markdown and MyST syntax when editing pages.

Find the owning page and branch

  • English pages are in docs/en/; Chinese pages are in docs/zh/. Product documentation is under each language’s MatrixOne/ directory. Keep related pages and navigation in sync across languages when the change applies to both.

  • main owns the latest documentation. Historical versions are separate branches; a change to main does not update them. Check the affected version and select the appropriate pull request base branch.

  • For an existing page, use its source path and update the relevant same-language navigation (toctree) if you add a new page. Do not edit generated HTML as the source of truth.

For a small correction, use Edit this page when available or open a documentation issue. Both languages are reviewed through matrixone-doc pull requests.

Contribute workflow

  1. Fork matrixone-doc, clone your fork, and add the upstream repository as a remote.

    git clone git@github.com:<yourname>/matrixone-doc.git
    cd matrixone-doc
    git remote add upstream https://github.com/matrixorigin/matrixone-doc.git
    
  2. Fetch the affected branch and create a topic branch from it. For the latest documentation:

    git fetch upstream main
    git switch -c docs/my-change upstream/main
    
  3. Edit the owning Markdown page(s). If you add a page, update the appropriate same-language toctree. Review links, code examples, and the equivalent page in the other language.

  4. Run focused checks. The site uses Sphinx, Furo, and MyST; uv manages the Python environment. For a main content change, a typical check is:

    uv sync
    make html-version VERSION=latest
    git diff --check
    

    For a historical version, use its configured version name. A narrow documentation edit does not require rebuilding every version. Do not commit build/ or generated artifacts.

  5. Commit and push your topic branch without force-pushing over main, then open a PR against the owning version branch. Explain the change, affected languages and versions, and the checks you ran.

    git add -p
    git commit -m "docs: describe my change"
    git push -u origin docs/my-change
    

The website is updated separately from source changes. A merged PR does not by itself prove that a particular deployed version has been rebuilt; verify the published page after deployment.

Contribute a blog article

For an article or idea, open an issue so the community can discuss it.