document-code

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Document Code

文档编写指南

Guide for adding and updating Syncpack's documentation website.

本文是为Syncpack文档网站添加和更新内容的指南。

Quick Decision

文档位置速查

What are you documenting?

Adding/Updating...	Location
Command docs	`site/src/content/docs/command/[cmd].mdx`
Config property	`site/src/content/docs/config/[prop].mdx`
Version group variant	`site/src/content/docs/version-groups/[var].mdx`
Semver group variant	`site/src/content/docs/semver-groups/[var].mdx`
Status code	`site/src/content/docs/status/[code].mdx`
FAQ	`site/src/faq/[id].mdx`
Shared option partial	`site/src/_partials/option/[opt].mdx`
Reusable component	`site/src/components/[name].astro`

你要编写/更新哪类文档？

文档类型	文件位置
命令文档	`site/src/content/docs/command/[cmd].mdx`
配置属性文档	`site/src/content/docs/config/[prop].mdx`
版本组变体文档	`site/src/content/docs/version-groups/[var].mdx`
语义化版本组变体文档	`site/src/content/docs/semver-groups/[var].mdx`
状态码文档	`site/src/content/docs/status/[code].mdx`
FAQ文档	`site/src/faq/[id].mdx`
共享选项片段	`site/src/_partials/option/[opt].mdx`
可复用组件	`site/src/components/[name].astro`

Workflow

工作流程

Read source —
```
cli.rs
```
for commands,
```
rcfile.rs
```
for config,
```
instance_state.rs
```
for status codes
Create/update MDX — Match existing structure exactly
Add link identifier — Update
```
globalReferenceLinks
```
in
```
astro.config.mjs
```
Test locally —
```
pnpm run dev
```
from
```
site/
```
Verify links — Check all
```
(IDENTIFIER)
```
links resolve

阅读源码 —— 命令相关内容查看
```
cli.rs
```
，配置相关查看
```
rcfile.rs
```
，状态码相关查看
```
instance_state.rs
```
创建/更新MDX文件 —— 严格匹配现有文档结构
添加链接标识符 —— 更新
```
astro.config.mjs
```
中的
```
globalReferenceLinks
```
本地测试 —— 在
```
site/
```
目录下执行
```
pnpm run dev
```
验证链接 —— 检查所有
```
(IDENTIFIER)
```
格式的链接是否能正常解析

Source to Docs Mapping

源码与文档对应关系

Source	Documentation
`src/cli.rs` Subcommand	`site/src/content/docs/command/*.mdx`
`src/rcfile.rs` Rcfile	`site/src/content/docs/config/*.mdx`
`src/instance_state.rs`	`site/src/content/docs/status/*.mdx`
`src/specifier.rs`	`site/src/content/docs/reference/specifier-types.mdx`

源码文件	对应文档位置
`src/cli.rs` 子命令	`site/src/content/docs/command/*.mdx`
`src/rcfile.rs` 配置文件	`site/src/content/docs/config/*.mdx`
`src/instance_state.rs`	`site/src/content/docs/status/*.mdx`
`src/specifier.rs`	`site/src/content/docs/reference/specifier-types.mdx`

Local Development

本地开发

bash

cd site
pnpm run dev          # Start at http://localhost:4321/syncpack
pnpm run build        # Verify build succeeds

bash

cd site
pnpm run dev          # 启动本地服务，地址为 http://localhost:4321/syncpack
pnpm run build        # 验证构建是否成功

Site Overview

网站概览

Source located at
```
site/src/
```
Built with Starlight on top of Astro
Content at
```
site/src/content/docs/**/*.mdx
```
Reusable partials at
```
site/src/_partials/**/*.mdx
```
Reusable components at
```
site/src/components/*.astro
```

源码位于
```
site/src/
```
基于 Astro 框架，使用 Starlight 构建
文档内容存储在
```
site/src/content/docs/**/*.mdx
```
可复用片段存储在
```
site/src/_partials/**/*.mdx
```
可复用组件存储在
```
site/src/components/*.astro
```

Command Documentation

命令文档规范

Each command has a corresponding file at

site/src/content/docs/command/[command].mdx

每个命令对应一个文档文件，路径为

site/src/content/docs/command/[command].mdx

。

Required Structure (in order)

必填结构（按顺序）

Description of the command's purpose from end user perspective
```
## Examples
```
— Single bash code block with commented examples
```
## Options
```
— Start with
```
<QuoteFilters />
```
callout, then
```
###
```
for each option alphabetically (
```
--help
```
last)

从用户视角描述命令的用途
```
## 示例
```
—— 单个bash代码块，包含带注释的示例
```
## 选项
```
—— 以
```
<QuoteFilters />
```
提示框开头，然后按字母顺序列出每个选项（
```
--help
```
放在最后）

Shared Option Partials

共享选项片段

Many commands share options. Define reusable partials at

site/src/_partials/option/*.mdx

mdx

import ConfigOption from "@partials/option/config.mdx";

<ConfigOption command="update" />

多个命令会共享相同的选项。可在

site/src/_partials/option/*.mdx

定义可复用片段：

mdx

import ConfigOption from "@partials/option/config.mdx";

<ConfigOption command="update" />

Config Documentation

配置文档规范

Each config property has a file at

site/src/content/docs/config/[property].mdx

每个配置属性对应一个文档文件，路径为

site/src/content/docs/config/[property].mdx

。

Required Structure

必填结构

Description of the config's purpose from end user perspective
```
## Default Value
```
— Code block showing default (when applicable)
```
## Examples
```
— Code blocks with commented examples

从用户视角描述配置的用途
```
## 默认值
```
—— 代码块展示默认值（如有）
```
## 示例
```
—— 代码块展示带注释的示例

Version Groups and Semver Groups

版本组与语义化版本组

Each variant has its own page:

site/src/content/docs/version-groups/*.mdx

site/src/content/docs/semver-groups/*.mdx

每个变体对应独立页面：

site/src/content/docs/version-groups/*.mdx

site/src/content/docs/semver-groups/*.mdx

Required Structure

必填结构

Description of the group's purpose from end user perspective
```
## Examples
```
— Code block per example, capture novel use cases
```
## Configuration
```
—
```
###
```
for each config property

从用户视角描述该组的用途
```
## 示例
```
—— 每个示例对应一个代码块，覆盖典型使用场景
```
## 配置
```
—— 每个配置属性对应一个
```
###
```
标题

Status Code Documentation

状态码文档规范

Each status code has a file at

site/src/content/docs/status/[code].mdx

Reference page at

site/src/content/docs/reference/status-codes.mdx

explains the

InstanceState

enum and its nested enums (

ValidInstance

InvalidInstance

SuspectInstance

每个状态码对应一个文档文件，路径为

site/src/content/docs/status/[code].mdx

。

参考页面

site/src/content/docs/reference/status-codes.mdx

解释了

InstanceState

枚举及其嵌套枚举（

ValidInstance

、

InvalidInstance

、

SuspectInstance

）。

FAQ Documentation

FAQ文档规范

Create FAQ files at
```
site/src/faq/[id].mdx
```
Listed at
```
/syncpack/faq
```
via
```
site/src/pages/faq.astro
```
Individual pages via
```
site/src/pages/faq/[id].astro
```

在
```
site/src/faq/[id].mdx
```
创建FAQ文件
通过
```
site/src/pages/faq.astro
```
在
```
/syncpack/faq
```
页面展示所有FAQ
单个FAQ页面路径为
```
site/src/pages/faq/[id].astro
```

Linking Between Pages

页面间链接规范

Use named identifiers in markdown links:

mdx

When using the [update](COMMAND_UPDATE) command

Define identifiers in

globalReferenceLinks

function in

site/astro.config.mjs

在Markdown链接中使用命名标识符：

mdx

使用 [update](COMMAND_UPDATE) 命令时

标识符需在

site/astro.config.mjs

的

globalReferenceLinks

函数中定义。

Open Graph Images

Open Graph 图片

Generated by

site/src/pages/og/[...path].png.ts

using Satori.

由

site/src/pages/og/[...path].png.ts

生成，使用 Satori 库。

Troubleshooting

常见问题排查

Problem	Fix
Link not working	Check identifier in `globalReferenceLinks`
Partial not rendering	Verify import path uses `@partials/` alias
OG image broken	Check `og/[...path].png.ts` handles new route
Build fails	Run `pnpm run build` locally to see error
Page not appearing in sidebar	Check frontmatter and Starlight config

问题现象	解决方法
链接无法正常跳转	检查 `globalReferenceLinks` 中是否存在对应标识符
片段无法渲染	验证导入路径是否使用 `@partials/` 别名
Open Graph图片加载失败	检查 `og/[...path].png.ts` 是否支持新路由
构建失败	本地执行 `pnpm run build` 查看具体错误信息
页面未显示在侧边栏	检查页面前置元数据与Starlight配置

Checklist

提交前检查清单

Before submitting documentation:

Structure matches existing pages of same type
Link identifier added to
```
astro.config.mjs
```
Local dev server renders correctly
Build succeeds (
```
pnpm run build
```
)
All internal links resolve

提交文档前请完成以下检查：

文档结构与同类型现有页面一致
已在
```
astro.config.mjs
```
中添加对应链接标识符
本地开发服务器能正常渲染页面
构建成功（执行
```
pnpm run build
```
）
所有内部链接均可正常解析