Documentation starts with writing

Write content in Markdown. The shared theme handles layout, typography, code presentation and search.

VitePress powers this site. Content and rendering configuration live separately, with no dependency on the XGC2 application runtime. Deployment consists of standalone static files.

Local development

Use Node.js 22 or later. Install the locked dependencies and start the development server:

npm ci
npm run dev

Open http://127.0.0.1:5176/docs/. The explicit /docs/ base path matches production. English pages live under /docs/en/.

Keep paths accurate

Page links and static resources must work under /docs/, so local previews match deployment behavior.

Separate content from the theme

Add documents under content/, theme and site configuration under site/, and public resources under content/public/. English translations mirror the Chinese page paths inside content/en/.

Location	Responsibility	Excludes
content/	Readable Markdown content	Page-specific style patches
site/.vitepress/theme/	Layout, typography and interactions	Product-specific facts
content/public/	Public resources	Private configuration and credentials

A minimal page

Begin with a clear title and a short introduction. Frontmatter provides metadata; the body follows a natural reading order:

---
title: Page name
description: What the reader will learn.
---

# Page name

Start the article here.

Heading hierarchy

Use one first-level heading. Second-level headings organize tasks; third-level headings explain steps or concepts within a task. Choose heading levels by structure.

Headings should describe their sections accurately and follow a continuous hierarchy.

Runnable code

Commands must come from real workflows and state their prerequisites. Do not invent flags, interfaces or outputs to fill a page.

Develop

npm ci
npm run dev

Validate

npm run build
npm run check

Use monospace for identifiers. Long configuration and command lines scroll inside code blocks without narrowing the reading column.

Before publishing

Build the full static site and run the publication checks:

npm run build
npm run check

Output is written to site/.vitepress/dist/. Pushes to the default branch run tests and build, publish over SFTP, and verify public HTTPS response bytes. Source files and server administration access are outside this publication path.

Build success is one part of validation

Verify navigation, search, code copying and appearance changes in a real browser when those features change.