文档结构标准

文档结构是读者阅读体验的骨架。统一的文档结构让读者在浏览不同命令文档时形成预期的阅读节奏，快速定位所需信息。本文档定义三种文档类型（命令、社区、基础）的章节结构规范。

一、命令文档结构

1.1 必须章节

每篇命令文档必须包含以下四个章节，缺一不可。章节顺序必须严格遵循以下顺序，不得调换。

第一章节：开头段落（无标题）

frontmatter 结束后，正文以一个无标题段落开始。不要使用任何 Markdown 标题（#、##、###）。

内容要求：

• 1-3 句话
• 概括命令的核心功能
• 如果命令有重要的版本变化信息，在此处简要提及
• 不要使用「本文档介绍……」之类的套话
• 不要在此处放置代码块或表格

正确示例：

给予玩家指定物品。基岩版 1.20.50+ 已弃用旧版数据值语法，改用物品组件系统。

管理计分板目标、玩家分数和显示设置。计分板是基岩版中实现数据追踪、条件判断和复杂游戏逻辑的核心工具。

错误示例：

# /give 命令

大家好！本教程将详细介绍 give 命令的各种用法。

第二章节：### 语法

标题必须为三级标题 ### 语法。不要使用 ## 语法（二级标题在详情页会被隐藏）或 #### 语法（四级标题层级不对）。

内容要求：

• 使用行内代码格式展示语法模板
• 如果命令有多个版本的语法（如新旧版本差异），分别列出并标注版本号
• 必填参数使用 <参数名> 格式
• 可选参数使用 [参数名] 格式
• 二选一参数使用 参数A | 参数B 格式
• 如果命令有多个子命令，列出所有子命令的语法

正确示例：

### 语法

**新版语法（1.20.50+）：**

`/give <玩家> <物品> [数量] [组件]`

**旧版语法（1.20.50 以下）：**

`/give <玩家> <物品> [数量] [数据值] [组件]`

### 语法

`/clone <起点> <终点> <目标位置> [遮罩模式] [克隆模式] [方块过滤]`

错误示例：

### 语法

/give <player> <item> [count]

（使用英文参数名、不使用行内代码格式）

第三章节：### 参数

标题必须为 ### 参数。

内容要求：

• 使用无序列表格式
• 每个参数一项
• 格式：- <参数名> — 参数说明
• 参数说明必须包含类型信息（选择器、整数、字符串、坐标等）
• 如果参数有有限的可选值，列出可选值
• 对于复杂命令（如 /execute、/scoreboard），可以使用子表格来组织参数

正确示例：

### 参数

- `<玩家>` — 目标选择器（如 `@p`、`@a`、`@s`）
- `<物品>` — 物品 ID（如 `diamond`、`stone`、`diamond_sword`）
- `[数量]` — 物品数量（1-64，默认 1）
- `[数据值]` — 旧版物品变体数据值（已弃用，1.20.50+ 使用独立物品 ID）
- `[组件]` — JSON 格式的物品组件

错误示例：

### 参数

- player: 目标玩家
- item: 物品

（使用英文、不使用连字符分隔、不含类型信息）

第四章节：### 示例

标题必须为 ### 示例。

内容要求：

• 至少 3 个示例
• 从简单到复杂排列
• 每个示例包含：示例标题（加粗文本）、代码块（mcfunction 语言标记）、效果说明（纯文本）
• 示例标题用加粗格式，以冒号结尾
• 代码块紧接标题，效果说明紧接代码块
• 示例中的命令必须是完整可执行的（包含所有必要参数）
• 不在代码块内添加注释

正确示例：

### 示例

**给予最近玩家 64 个钻石：**
<CmdChat>`/give @p diamond 64`

给予最近的玩家 64 个钻石。

**给予所有玩家一把钻石剑：**
<CmdChat>`/give @a diamond_sword 1`

给服务器中所有在线玩家各一把钻石剑。

**给予一把锋利 V 钻石剑（基岩版先给予再附魔）：**
<CmdChat>`/give @s diamond_sword`
<CmdChat>`/enchant @s sharpness 5`

基岩版 `/give` 无法直接附魔，先给予未附魔的钻石剑，再手持后执行 `/enchant` 附魔。

错误示例：

### 示例

/give @p diamond

（只有一个示例、没有标题、没有代码块语言标记、没有效果说明）

第五章节：### 基岩版注意

标题必须为 ### 基岩版注意。

内容要求：

• 使用无序列表
• 每条注意为一个列表项
• 必须包含 OP 等级要求
• 必须包含与 Java 版的主要差异（如果存在）
• 必须包含版本兼容性问题（如果存在）
• 不使用提示框语法（> [!NOTE] 等），直接用列表

正确示例：

>[!NOTE]
> - 1.20.50+ 版本弃用了物品数据值，改用独立物品 ID（如花岗岩从 `stone 1` 变为 `granite`）
> - 物品组件语法在近期版本中有较大变化，建议查阅对应版本的 Wiki
> - 旧版命令中使用数据值 0 的物品可省略数据值参数
> - 需要 OP 等级 1

1.2 可选章节

以下章节根据命令的复杂度选择性添加。如果命令涉及对应的概念，应添加对应章节。

1.3 章节顺序

完整的章节顺序如下（必须章节用 [必须] 标注，可选章节用 [可选] 标注）：

1. [必须] 开头段落（无标题）
2. [可选] 子命令一览（### 子命令一览）
3. [必须] 语法（### 语法）
4. [必须] 参数（### 参数）
5. [可选] 各类参数子章节（遮罩模式、克隆模式、常用物品 ID 等）
6. [必须] 示例（### 示例）
7. [必须] 基岩版注意（### 基岩版注意）
8. [可选] 常见问题（### 常见问题）

二、社区文档结构

社区文档没有严格的必须章节要求，但应遵循以下要素结构：

2.1 功能描述（开头段落）

与命令文档相同，开头用 1-3 句话说清楚功能做什么。

2.2 前置指令（### 前置指令）

如果功能需要玩家先在聊天栏执行一些命令来创建基础设置（如计分板、游戏规则等），使用此章节列出。

要求：

• 每个前置指令使用 <CmdChat> 组件
• 在指令前简要说明这个指令做什么
• 按执行顺序排列

正确示例：

### 前置指令

在聊天栏中依次执行：

<CmdChat>`/scoreboard objectives add 雪球菜单 dummy`

<CmdChat>`/gamerule commandblockoutput false`

2.3 搭建步骤

按步骤列出命令方块的摆放方式和指令内容。

要求：

• 使用 ### 或 #### 分组标题
• 每个指令使用对应的 <CmdXxx> 组件
• 注明命令方块类型（脉冲/重复/连锁/条件）
• 注明命令方块设置（保持开启/需要红石等）
• 指令编号递增
• 必要时使用加粗标题解释指令功能

2.4 常见问题（### 常见问题 或 <details> 折叠）

使用 <details> / <summary> 折叠内容列出常见问题。

2.5 基岩版注意（### 基岩版注意）

如果存在版本差异，列出注意事项。

三、基础文档结构

基础文档结构最为灵活，但应遵循以下基本要求：

• 使用 ## 作为顶级章节标题（不要用 #）
• 章节之间逻辑连贯
• 有目录感——读者能快速扫描标题了解文档覆盖范围
• 标准规范文档应包含：总则、分则、附则

四、标题层级规范

MCBECD 站点对 Markdown 标题有以下处理：

• #（一级标题）：站点不使用
• ##（二级标题）：用于基础文档的主要章节
• ###（三级标题）：用于命令文档的章节标题
• ####（四级标题）：用于三级标题下的子分组

重要：在命令文档的详情页中，##（二级标题）会被隐藏（因为详情页的标题卡片已经显示了文档标题）。因此命令文档必须使用 ### 作为最高级别的标题。

禁止：

• 跳级（如从 ### 直接到 #####）
• 在同一个文档中使用多种标题层级风格

五、内容深度要求

5.1 最低字数

5.2 段落深度

• 每个段落至少 2 句话
• 单句话段落只用于过渡或强调
• 参数说明不能只有类型名，必须有文字解释
• 示例说明不能只有命令文本，必须描述执行效果

5.3 示例数量