MD 组件使用标准

MCBECD 站点支持多种自定义 MD 组件，用于增强文档的表现力。这些组件由 MDRenderer.tsx 注册，在所有 .md 文档中可直接使用。本文档逐一说明每种组件的用途、语法、使用规则和常见错误。

一、命令方块图标组件

1.1 概述

命令方块图标组件用于在文档中展示命令在命令方块中的执行方式。每个组件会在命令文本前显示一个 16x16 像素的 Minecraft 命令方块图标，后跟等宽字体的命令文本。

站点共注册了 7 种命令方块图标组件，对应 7 种命令方块类型。

1.2 组件列表

组件名	方块类型	触发条件
`<CmdImpulse>`	无条件脉冲	收到红石信号时执行一次
`<CmdRepeat>`	无条件循环	每个游戏刻持续执行
`<CmdChain>`	无条件连锁	在指向它的命令方块执行后触发
`<CmdConditionalImpulse>`	条件脉冲	仅在上一个命令方块成功时执行一次
`<CmdConditionalRepeat>`	条件重复	仅在上一个成功时每个刻执行
`<CmdConditionalChain>`	条件连锁	仅在上一个成功时触发

说明：<CmdImpulse> 组件一般用于红石触发。仅需执行一次的命令使用```包裹。

1.3 使用语法

<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 传送`

语法规则：

命令文本放在组件的开始标签和结束标签之间
命令文本不需要 / 前缀（命令方块中执行命令不输入 /）
命令文本应为完整的、可直接复制的命令
组件标签和命令文本之间不要有空行

二、GitHub 风格提示框

2.1 概述

MCBECD 站点通过 remark-github-alerts 插件支持 GitHub 风格的提示框。提示框用于在文档中插入不同级别的重要信息。

2.2 基本语法

> [!NOTE]
> 这是一条普通提示信息。

> [!TIP]
> 这是一个实用技巧。

> [!IMPORTANT]
> 这是重要信息，需要特别注意。

> [!WARNING]
> 这是警告信息。

> [!CAUTION]
> 这是危险操作警告，请谨慎执行。

2.3 自定义标题

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

> [!TIP] 性能优化
> 使用 `@e[type=item,c=1]` 限制搜索范围以提高性能。

2.4 类型选择指南

类型	颜色	使用场景	示例
`NOTE`	蓝色	补充说明、额外信息、背景知识	"基岩版 1.19.50 开始支持旁观模式"
`TIP`	绿色	实用技巧、最佳实践、性能优化建议	"使用 `c=1` 限制搜索数量可提高性能"
`IMPORTANT`	紫色	重要信息、关键要点、必须记住的规则	"此命令需要 OP 等级 2"
`WARNING`	橙色	注意事项、潜在问题、版本兼容性	"网易版中此命令语法有差异"
`CAUTION`	红色	危险操作、不可逆操作、可能导致数据丢失	"大面积 fill air 操作不可逆"

2.5 使用规则

提示框内容应简洁，1-3 句话
不要在提示框中放置代码块（代码块会被当作普通文本）
不要嵌套提示框
在命令文档中，基岩版注意 章节使用列表格式，不使用提示框
提示框适用于正文中需要特别强调的信息

三、折叠内容

3.1 语法

<details>
<summary>点击展开详细信息</summary>

折叠的详细内容放在这里。

</details>

3.2 使用规则

适合 FAQ、补充说明、长篇幅内容
<summary> 内容应简洁（5-15 个字）
折叠内容内可以包含任何 Markdown/MD 内容（代码块、表格、列表等）
核心文档内容不应放在折叠中（折叠内容是可选阅读的）
不要嵌套折叠

3.3 使用场景

社区文档的「常见问题」章节
命令文档的附加说明（如高级用法、版本迁移等）
基础文档的补充材料

四、代码块

4.1 基本语法

使用三个反引号围栏，指定语言标记：

<CmdChat>`/give @p diamond 64`

4.2 语言标记

标记	用途	高亮支持
`mcfunction`	Minecraft 命令	完整高亮（命令名、选择器、字符串、数字、参数）
`json`	JSON 格式	通用 JSON 高亮
`bash`	Shell 命令	仅限开发相关文档
`yaml`	YAML 格式	仅限 frontmatter 示例
无标记	纯文本	降级为 mcfunction 高亮

4.3 mcfunction 高亮规则

站点内置了自定义的 mcfunction 语法高亮规则（lib/md/mcfunction.json）。自动识别以下元素：

元素	高亮方式	示例
命令名	函数名颜色	`give`、`execute`、`scoreboard`
选择器	标签颜色	`@p`、`@a`、`@s`、`@e`
字符串	字符串颜色	`"text"`、`'text'`
布尔值	常量颜色	`true`、`false`
数字	数值颜色	`100`、`64`、`0`
坐标	数值颜色	`~ ~1 ~`、`^ ^ ^1`
参数名	参数颜色	`sharpness`、`speed`、`dummy`

4.4 使用规则

命令示例必须使用 mcfunction 语言标记
JSON 组件示例使用 json 标记
代码块内的命令必须是完整可执行的
不在代码块内添加注释或说明文字（说明写在代码块外部）
代码块和前后文本之间各留一个空行

五、表格

5.1 基本语法

| 列标题1 | 列标题2 | 列标题3 |
|---------|---------|---------|
| 数据1 | 数据2 | 数据3 |
| 数据4 | 数据5 | 数据6 |

5.2 使用规则

表头行必须有分隔线（|---|---|）
列标题不能为空
表格内容对齐
大表格建议按功能分组
表格不应有过多的列（建议不超过 5 列）

5.3 渲染效果

站点引擎（MDRenderer.tsx）会自动为表格添加以下样式：

外层包裹 overflow-x-auto 容器（支持横向滚动）
表格添加边框 border border-[var(--color-border)]
表头添加背景色 bg-[var(--color-bg-tertiary)]
单元格添加内边距 px-4 py-2

六、内联代码

使用反引号包裹代码片段：

使用 `@p` 选择最近玩家。
物品 ID 为 `diamond_sword`。

使用场景：

命令名称（在不需要链接的上下文中）
参数名
物品 ID
选择器
文件名
配置项名称

七、键盘按键

使用 <kbd> 标签显示键盘按键：

按 <kbd>Ctrl</kbd> + <kbd>C</kbd> 复制代码。
按 <kbd>T</kbd> 打开聊天栏。

八、禁止使用的 Markdown 特性

以下 Markdown 特性在 MCBECD 文档中禁止使用：

HTML 标签（<div>、<span>、<img> 等），除了 MD 自定义组件和 <kbd>、<details>、<summary> 之外
脚注（[^1]）
自动链接（直接写 URL 不加括号）
图片（![]()）—— MCBECD 文档暂不支持图片
任务列表（- [ ] 和 - [x]）—— 虽然站点引擎支持，但不推荐使用