MCBECD 文档标准总纲

本文档是 MCBECD 文档项目的唯一权威标准来源。所有贡献者、维护者在编写和审核文档时，必须以本文档为准。任何与本文档冲突的旧文档、旧指南、旧模板，均以本文档为准。

如果你是第一次参与贡献，请按顺序阅读以下章节：

1. Frontmatter 规范
2. 标签体系
3. 文件命名规则
4. 文档结构规范
5. 写作深度要求
6. 交叉引用规范
7. MD 组件使用规范
8. 社区文档规范
9. 校验与审核流程

每个 .md 文件的顶部必须包含 YAML frontmatter，用 --- 包裹。frontmatter 是文档的元数据，决定了文档在站点上的显示方式、排序、分类和检索行为。

1.1 字段总览

1.2 title 字段

title 是文档在站点上显示的标题。不同类型的文档有不同的标题格式。

命令文档的标题格式：

/command  中文名称

规则：

• 命令名前必须有 / 前缀
• /command 和中文名称之间用两个空格分隔
• 中文名称使用命令的常用中文叫法
• 不在标题中使用 Markdown 格式（不加粗、不加代码包裹）

正确示例：

title: "/give  给予物品"
title: "/execute  执行命令"
title: "/scoreboard  计分板"
title: "/particle  粒子效果"

错误示例：

title: "give 命令"           # 缺少 / 前缀
title: "/give 给予物品"        # 只有一个空格
title: "**/give**  给予物品"   # 不要 Markdown 格式
title: "Give command"          # 不要英文

社区文档的标题格式：

规则：

• 直接使用功能名称，不加前缀
• 名称简洁明确，一般不超过 10 个汉字
• 不加引号、不加 Markdown 格式

正确示例：

title: "雪球菜单"
title: "在线时间"
title: "雪球填平"

基础文档的标题格式：

基础文档的标题无固定格式，但应简洁明确。

1.4 description 字段

description 是文档的一句话描述，显示在文档列表和搜索结果中。

规则：

• 长度控制在 15-40 个汉字之间
• 必须是完整的一句话，以句号结尾（也可以不加句号）
• 描述文档的核心功能或内容，不要写「本文档介绍……」之类的废话
• 不要使用 Markdown 格式

正确示例：

description: "给予玩家指定物品，支持数量、数据值与组件"
description: "丢雪球打开菜单，支持传送主城、去世、切换模式、设重生点、发起/接受传送"
description: "基岩版命令的参数格式、目标选择器与坐标系统"

错误示例：

description: "介绍give命令的用法"       # 废话，没有信息量
description: "give"                      # 太短
description: "这是一个非常强大的命令，可以给玩家物品，也可以给物品附加附魔，还可以锁定物品"  # 太长
description: "**给予物品**"               # 不要 Markdown 格式

1.5 author 字段

author 是文档的作者署名。

规则：

• 使用你的 MCBECD 社区名称或 GitHub 用户名
• 格式统一为 字符串，不加引号外的括号
• 如果是多人协作，用逗号分隔

正确示例：

author: "官方•Dingding OvO"
author: "Steve"
author: "Alex, Steve"

1.6 updatedAt 字段

updatedAt 是文档的最后更新日期。

规则：

• 格式必须是 YYYY-MM-DD（ISO 8601 日期格式）
• 每次修改文档内容时必须更新此字段
• 使用当天的日期，不要使用未来日期

1.7 tags 字段

tags 是文档的标签数组。详细规范见第二章「标签体系」。

1.9 完整 frontmatter 模板

命令文档模板：

---
author: "你的名字"
updatedAt: "2026-08-12"
title: "/command  中文名称"
description: "一句话描述命令功能"
tags: ["领域标签", "场景标签", "属性标签"]
---

社区文档模板：

---
author: "你的名字"
updatedAt: "2026-08-12"
title: "功能名称"
description: "一句话描述这个功能做什么"
tags: ["内容类型", "技术栈", "标签"]
---

基础文档模板：

---
author: "你的名字"
updatedAt: "2026-08-12"
title: "文档标题"
description: "一句话描述"
tags: ["标准"]
---

标签是 MCBECD 文档系统的检索骨架。每篇文档通过 tags 字段挂载标签，站点前端根据标签进行筛选、搜索和推荐。

2.1 标签分类

标签分为三层：领域标签、场景标签、属性标签。所有标签均为简体中文。

领域标签（13 个）

描述命令操作的核心对象。每篇命令文档必须且只能有 1 个领域标签。

场景标签（12 个）

描述命令的典型使用环境。每篇文档至少 1 个场景标签。

属性标签（13 个）

描述命令的自身特性。属性标签可选但强烈推荐。

社区专用标签（10 个）

仅社区文档使用。

内容类型（选 1 个）：

技术栈（选 1-2 个）：

元标签（2 个）

2.2 每篇文档的标签规则

命令文档（必须遵守）：

1. 必须有且仅有 1 个领域标签
2. 必须有 1-3 个场景标签
3. 必须有 1-2 个属性标签（OP 等级标签优先）
4. 标签总数控制在 3-7 个
5. 书写顺序：领域标签 → 场景标签 → 属性标签

社区文档（必须遵守）：

1. 必须有 1 个内容类型标签
2. 必须有 1-2 个技术栈标签
3. 可选添加场景/属性标签
4. 标签总数控制在 3-6 个

基础文档（可选）：

1. 可加 标准 或 入门 元标签
2. 不加领域/场景/属性标签

2.3 全部命令的标签对照表

以下表格规定了每个命令文档必须使用的标签。维护者审核 PR 时对照此表检查。

2.4 标签书写语法

tags: ["标签A", "标签B", "标签C"]

规则：

• 标签用方括号包裹
• 每个标签用双引号包裹
• 标签之间用逗号+空格分隔
• 标签名使用简体中文
• 标签内不含空格

3.1 命令文档

命令文档存放在 commands/ 子目录下，文件名为命令名（不含 /）。

规则：

• 文件名 = 命令名（小写）+ .md
• 不含 / 前缀
• 不含空格
• 全部小写

正确示例：

commands/give.md
commands/execute.md
commands/scoreboard.md

3.2 社区文档

社区文档存放在仓库根目录，文件名为纯数字。

规则：

• 文件名 = 数字编号 + .md
• 编号从 1 开始递增
• 新增社区文档使用下一个可用编号
• 不含任何单词或字母前缀

正确示例：

1.md
2.md
3.md

3.3 基础文档

基础文档存放在仓库根目录，文件名为语义化的英文小写。

规则：

• 使用小写英文
• 单词之间用连字符 - 分隔
• 名词或名词短语

现有基础文档：

about.md
getting-started.md
command-syntax.md
writing-guide.md
standards.md

3.4 目录结构总览

MCBECD/docs/
├── CONTRIBUTING.md
├── README.md
├── commands/
│   ├── ability.md
│   ├── clear.md
│   ├── clone.md
│   ├── difficulty.md
│   ├── effect.md
│   ├── enchant.md
│   ├── execute.md
│   ├── fill.md
│   ├── gamemode.md
│   ├── gamerule.md
│   ├── give.md
│   ├── help.md
│   ├── kill.md
│   ├── locate.md
│   ├── particle.md
│   ├── playsound.md
│   ├── ride.md
│   ├── scoreboard.md
│   ├── setblock.md
│   ├── summon.md
│   ├── tag.md
│   ├── time.md
│   ├── title.md
│   ├── tp.md
│   ├── weather.md
│   └── xp.md
├── community/
│   ├── 1.md
│   ├── 2.md
│   ├── 3.md
│   ├── 4.md
│   └── 5.md
├── standards/
│   ├── community-standard.md
│   ├── crossref-standard.md
│   ├── frontmatter-standard.md
│   ├── glossary-standard.md
│   ├── naming-standard.md
│   ├── review-standard.md
│   ├── structure-standard.md
│   ├── tag-standard.md
│   ├── version-compat-standard.md
│   └── writing-quality-standard.md
├── about.md
├── command-syntax.md
├── getting-started.md
├── standards.md
├── standards.md-components-standard.md
└── writing-guide.md

4.1 命令文档的必须章节

每篇命令文档必须包含以下章节，缺一不可。

开头段落

frontmatter 之后的第一段必须是命令的一句话功能描述。不要用标题，直接写正文。

规则：

• 1-3 句话
• 概括命令的核心功能
• 不要写「本文档介绍……」之类的套话
• 如果命令在不同版本间有重大变化，在此处简要提及

正确示例：

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

错误示例：

# /give 命令
本教程将详细介绍 give 命令的各种用法和参数。

语法章节

标题为 ### 语法。

规则：

• 使用行内代码格式展示语法：`/command <参数> [可选参数]`
• 如果命令有多个版本语法（如新旧版本），分别列出并标注版本号
• 参数使用尖括号 <参数> 表示必填，方括号 [参数] 表示可选
• 竖线 | 表示二选一

正确示例：

### 语法

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

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

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

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

参数章节

标题为 ### 参数。

规则：

• 使用列表格式，每个参数一项
• 格式：- <参数名> — 参数说明
• 说明应包含参数的类型（选择器、整数、字符串等）
• 如果参数有可选值，列出可选值
• 复杂命令的参数可以拆分为子表格

正确示例：

### 参数

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

示例章节

标题为 ### 示例。

规则：

• 至少 3 个示例
• 从简单到复杂排列
• 每个示例必须包含代码块和效果说明
• 代码块使用 mcfunction 语言标记
• 效果说明用普通文本写在代码块下方
• 示例应该是可以直接复制使用的完整命令

正确示例：

### 示例

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

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

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

基岩版注意章节

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

规则：

• 列出该命令在基岩版中的特殊行为
• 与 Java 版的差异必须提及
• 版本兼容性问题必须提及
• OP 等级要求必须提及
• 每条注意使用列表项

正确示例：

>[!NOTE]
> - 1.20.50+ 版本弃用了物品数据值，改用独立物品 ID
> - 物品组件语法在近期版本中有较大变化，建议查阅对应版本的 Wiki
> - 需要 OP 等级 1

4.2 可选章节

以下章节根据需要添加，不是必须的。

4.3 社区文档的结构

社区文档没有固定的章节要求，但应包含以下要素：

1. 功能描述：开头用 1-3 句话说清楚这个功能做什么
2. 前置指令：如果需要提前执行一些命令创建基础设置（如计分板），用 ### 前置指令 章节列出，每个指令使用 <CmdChat> 组件
3. 搭建步骤：按步骤列出命令方块的摆放方式和指令内容
4. 常见问题：用 <details> / <summary> 折叠内容列出常见问题和解决方案
5. 基岩版注意：如果存在版本差异，列出注意事项

5.1 最低字数要求

5.2 示例数量要求

5.3 段落深度要求

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

5.4 代码块要求

• 命令示例必须使用 mcfunction 语言标记
• 其他代码（如 JSON）使用 json 标记
• 代码块内不要加注释说明（说明写在代码块外部）
• 每个代码块内的命令应该是完整可执行的

6.1 命令之间的引用

在文档中引用其他命令时，必须使用反引号包裹命令文本，并链接到对应文档。

规则：

• 链接文字用反引号包裹：`/give`
• 使用相对路径链接（相对于当前文档所在目录，../ 表示向上一层）
• 命令文档之间的链接（都在 commands/ 下）：[文本](../command-name/)
• 社区文档（community/）链接到命令：[文本](../../commands/command-name/)
• 基础文档（根目录）链接到命令：[文本](../../commands/command-name/)
• 命令文档链接到基础文档（commands/ → 根目录）：[文本](../../basics-doc-name/)

正确示例（从命令文档 commands/give 出发）：

详见 [`/execute`](../execute/) 命令文档。

配合 [`/summon`](../summon/) 在不同上下文中执行命令。

更多选择器用法见[命令语法基础](../../command-syntax/)。

错误示例：

详见 /give 命令。          # 没有链接
详见 /give(./give)。        # 路径错误
详见 give。                  # 缺少 / 前缀和链接

6.2 链接路径规则

注意：链接路径末尾带 /，不带 .md 后缀。完整的相对路径规则见交叉引用标准。

MCBECD 站点支持自定义 MD 组件，用于增强文档的表现力。

7.1 命令方块图标组件

用于展示命令在命令方块中的执行方式。共 7 种组件：

使用规则：

1. 前置指令（需要玩家在聊天栏手动输入的命令）使用 <CmdChat>
2. 循环方块中的命令使用 <CmdRepeat>
3. 连锁方块中的命令使用 <CmdChain>
4. 条件连锁方块中的命令（成功时才执行）使用 <CmdConditionalChain>
5. 命令文本放在组件的开始和结束标签之间

正确示例：

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

<CmdRepeat>`/scoreboard players add @a 在线时间 1`

<CmdChain>`/execute at @e[type=snowball] run kill @e[type=snowball,c=1,r=2]`

<CmdConditionalChain>`/scoreboard objectives remove 传送`

选择指南：

• 命令描述中提到「循环」「每个刻」「保持开启」→ <CmdRepeat>
• 命令描述中提到「连锁」「被触发」「指向它」→ <CmdChain>
• 命令描述中提到「有条件」「上一个成功时」→ <CmdConditionalChain>
• 命令描述中提到「聊天栏」「手动输入」→ <CmdChat>
• 命令描述中提到「脉冲」「收到信号」→ <CmdImpulse>

7.2 GitHub 风格提示框

用于插入不同级别的提示信息。

> [!NOTE]
> 普通提示。

> [!TIP]
> 实用技巧。

> [!IMPORTANT]
> 重要信息。

> [!WARNING]
> 警告信息。

> [!CAUTION]
> 危险操作警告。

也可以自定义标题：

> [!WARNING] 基岩版独有
> 此命令在 Java 版中不可用。

使用规则：

• NOTE：补充说明、额外信息
• TIP：实用技巧、最佳实践
• IMPORTANT：重要信息、关键要点
• WARNING：注意事项、潜在问题
• CAUTION：危险操作、不可逆操作
• 在命令文档中，基岩版注意 章节的内容不使用提示框，直接用列表

7.3 折叠内容

用于 FAQ 或可折叠的补充内容。

<details>
<summary>点击展开</summary>

折叠内容。

</details>

使用规则：

• FAQ 类内容必须使用折叠
• 长篇幅的补充内容建议折叠
• 不要在折叠内容中放置核心文档内容（折叠内容是可选阅读的）

7.4 代码块

使用标准围栏语法，指定语言标记。

<CmdChat>`/give @p diamond 64`

语言标记选择：

7.5 表格

使用标准 GFM 表格。表头必须完整，每列对齐。

| 参数 | 类型 | 说明 |
|------|------|------|
| `<玩家>` | 选择器 | 目标玩家 |

7.6 内联代码

使用反引号包裹命令、参数名、物品 ID 等代码片段。

使用 `@p` 选择最近玩家。

物品 ID 为 `diamond_sword`。

7.7 键盘按键

使用 <kbd> 标签。

按 <kbd>Ctrl</kbd> + <kbd>C</kbd> 复制。

8.1 文档范围

社区文档收录以下类型的内容：

• 命令方块搭建教程（如雪球菜单、自动售货机）
• 计分板系统教程（如在线时间、经济系统）
• 红石+命令结合的创意玩法
• 服务器管理工具和脚本
• 原版命令实现的实用功能

不收录的内容：

• 纯红石电路（不涉及命令）
• 需要附加包/模组才能实现的功能
• 与命令无关的游戏攻略

8.2 社区文档的 frontmatter

---
author: "作者名"
updatedAt: "2026-08-12"
title: "功能名称"
description: "一句话描述"
tags: ["内容类型", "技术栈"]
---

8.3 社区文档的编号分配

• 编号从 1 开始递增
• 新增文档使用下一个可用编号
• 不要跳号
• 不要重用已删除文档的编号
• 纯数字，不补零，不加前缀

8.4 社区文档的质量要求

• 所有命令方块指令必须使用对应的 <Cmdxx> 组件
• 前置指令（聊天栏执行的）必须用 <CmdChat> 并明确说明
• 每个步骤的命令方块类型（脉冲/重复/连锁/条件）必须写明
• 常见问题必须用 <details> 折叠
• 如果涉及版本差异，必须有「基岩版注意」章节

9.1 提交前自检

在提交 PR 之前，贡献者应检查以下项目：

Frontmatter 检查：

• title 格式正确（命令文档：/command 中文名）
• description 长度在 15-40 字之间
• author 已填写
• updatedAt 为今天或最近的日期
• tags 已填写且符合标签对照表

内容检查：

• 命令文档包含语法、参数、示例、基岩版注意四个章节
• 示例数量至少 3 个
• 所有命令引用使用了反引号+链接
• 代码块使用了正确的语言标记
• 命令方块指令使用了 <Cmdxx> 组件
• 交叉引用使用了相对路径

9.2 维护者审核

维护者在审核 PR 时应检查：

1. 对照标签对照表检查 tags 是否正确
2. 检查 frontmatter 是否完整且格式正确
3. 检查文档结构是否包含所有必须章节
4. 检查交叉引用路径是否正确
5. 检查 MD 组件使用是否正确
6. 检查内容是否有事实性错误
7. 检查中文写作质量（无错别字、语句通顺）

9.3 标准更新流程

1. 如需新增标签，先在 standards/tag-standard.md 中更新标签索引和对照表，再在本文件中同步更新
2. 如需新增文档类型或修改 frontmatter 规则，直接修改本文件
3. 标准更新后，所有现有文档应在合理时间内完成迁移
4. 重大标准变更需在 Issue 中讨论并获得维护者批准

按使用频率排列的最常用标签：