编写规范
本文档用于说明 PCLC Docs 的内容编写规范，包括条目收录范围、行文视角、语言风格、格式要求、术语使用、示例写法以及参考标准等内容。
本文规范适用于 PCLC Docs 下的所有文档。除 PCL CE 外，若 PCL Community 后续维护其他项目、工具、服务或开发者文档，也应遵循本文规范。针对特定项目的专用规范，可以在对应项目文档中另行补充，但不应与本文的通用要求冲突。
所有新增文档和对既有文档的大幅修改，均应尽可能遵循本文规范。若因特殊情况无法完全遵守，应在 Pull Request 描述中说明原因，方便维护者审核。
一、编写前检查
在创建新的帮助条目之前，应先确认该内容是否适合收录到 PCLC Docs 中。
1. 检查站内是否已有相关内容
创建新条目前，应先在文档站点中搜索相关关键词，确认站点中尚未收录相同或高度重复的内容。
若已有相近内容，应优先考虑修改或补充既有页面，而不是创建新的重复页面。
2. 检查是否已有相关 Pull Request
创建新条目前，应查看文档仓库在 GitHub 上的 Pull Requests，确认没有其他贡献者正在编辑相同或相近内容。
若已有相关 Pull Request，可以在对应讨论中补充建议，或等待该 Pull Request 合并后再继续修改。
3. 确认内容与 PCL Community 及其项目有关
新增条目必须与 PCL Community、PCLC Docs 或 PCL Community 维护的具体项目具有明确关联。
这里的“项目”包括但不限于：
- PCL Community 维护的启动器或相关应用；
- PCL Community 维护的核心库、工具链或开发组件；
- PCL Community 维护的文档站点、规范文档或贡献指南；
- 与上述项目直接相关，且用户或开发者确实可能需要了解的外部服务说明。
以下内容通常适合收录：
- PCL Community 旗下项目的安装、配置和使用说明；
- PCL Community 旗下项目中具体功能的说明或教程；
- PCL Community 旗下项目的常见问题排查方法；
- 与项目开发、文档贡献、项目规范相关的内容；
- 与项目使用场景直接相关，且具有长期参考价值的外部服务说明。
以下内容通常不应收录：
- 与 PCL Community 及其项目无直接关系的内容；
- 仅适用于极少数特殊场景，且缺乏长期参考价值的内容；
- 时效性过强、短期内可能失效的内容；
- 与项目无关的纯 Minecraft 游戏机制说明；
- 仅表达个人经验、个人观点或个人偏好的内容。
4. 区分 PCLC Docs 与 Minecraft Wiki
PCLC Docs 不是 Minecraft Wiki，不应收录纯游戏机制、玩法百科或与 PCL Community 项目无关的游戏教程。
若需要编写纯 Minecraft 游戏相关内容，应前往 Minecraft Wiki 教程页面。
例如，以下内容通常不适合收录到 PCLC Docs：
- 如何击败末影龙；
- 如何建造刷怪塔；
- 如何制作红石电梯；
- 某个 Minecraft 版本新增了哪些方块。
但如果内容与 PCL Community 项目的功能、使用场景或排障流程直接相关，则可以收录。例如：
- 如何使用 PCL CE 安装 Minecraft；
- 如何在 PCL CE 中安装 Mod；
- 如何在 PCL CE 中配置 Java；
- 如何排查 PCL CE 启动 Minecraft 失败的问题；
- 某个项目依赖 Minecraft 资源结构时，对相关目录的必要说明。
5. 参考已有合格页面
编写新页面时，可以参考站点中已经过审核的既有页面。
优先参考顶部未标注“需要重新整理格式”“需要优化排版”等提示的页面。这些页面通常已经经过维护者审核，可以作为结构、语气和排版的参考。
可以复制类似页面作为模板，但必须根据实际内容修改标题、正文、图片、链接和示例，不得保留与新页面无关的内容。
二、基本写作原则
1. 使用官方视角
文档内容代表 PCL Community 及对应项目的官方说明，因此应使用官方视角编写，不应使用个人视角。
不应使用“我”“我们觉得”“我推荐”“我的经验是”等个人化表达，除非该页面明确是署名文章、讨论记录或其他特殊说明页面。
错误示例：
我觉得这个功能很好用，你可以试试看。推荐写法：
该功能可用于快速完成相关配置，适合需要重复执行相同操作的场景。错误示例：
要修改这一堆条目，你去提交 Pull Request 后还得等审核才可以。推荐写法：
若需要修改 PCLC Docs 中的文档内容，可以提交 Pull Request。提交后，仍需等待维护者审核。2. 使用正式书面语
文档应使用清晰、正式、稳定的说明文语言。应避免口语化、情绪化、玩笑式或社交媒体式表达。
不应使用以下表达方式：
- “一堆”“乱七八糟”“很坑”“很离谱”等口语或情绪表达；
- “你就无脑点下一步”“随便填一下”等不严谨表达；
- “众所周知”“懂的都懂”等缺乏说明的信息；
- “非常牛”“超好用”“强烈安利”等评价性表达。
错误示例：
这里会有一堆奇怪的问题，反正你重装一下就好了。推荐写法：
若该步骤出现异常，可以尝试重新安装相关组件，并确认安装路径和版本是否符合要求。3. 使用客观说明文体
文档应以说明事实、解释步骤和描述结果为主，尽量避免剧情化、宣传化或评价性叙述。
错误示例：
整合包里有许多好玩的 Mod，但下载之后如何安装却成了大家的一大疑惑，这篇教程会教会你如何安装。推荐写法：
下载整合包后，还需要完成导入或安装操作才能进行游戏。本文介绍在启动器中安装整合包的方法。4. 避免主观评价
除非确有必要，不应使用主观评价描述功能、软件、服务或用户行为。
错误示例：
这个方法最简单，也最适合小白。推荐写法：
该方法操作步骤较少，适合首次配置的用户。错误示例：
这个功能没什么用，不建议打开。推荐写法：
若不需要该功能提供的相关能力，可以保持关闭状态。5. 避免不必要的时效性叙述
文档内容应尽量保持长期有效。涉及时间时，应使用明确日期，不应使用“今年”“最近”“新版”“目前”等容易过期的表达。
错误示例：
Mojang 在今年 4 月更新了 1.14，更新内容很多。推荐写法：
Mojang 在 2019 年 4 月发布了 Java 版 1.14。若内容确实具有时效性，应尽量注明具体版本、日期或适用范围。
三、受众与内容深度
编写文档时，应根据页面面向的读者决定说明深度。
1. 面向普通用户的文档
面向普通用户的文档应尽量详细说明操作路径、前置条件和可能结果。
适合包含以下内容：
- 操作入口；
- 每一步需要点击或填写的内容；
- 操作完成后的预期结果；
- 常见错误及处理方法；
- 必要截图；
- 对专业名词的简要解释。
示例：
打开对应项目后，进入“设置”页面。如果列表中没有可用配置项，可以点击“自动搜索”或“刷新”让程序重新扫描本机环境。若文档只适用于某个具体项目，应在页面开头或相关章节中明确说明。
示例：
本文仅适用于 PCL CE。其他 PCL Community 项目可能不包含相同的设置入口。2. 面向高级用户的文档
面向高级用户、开发者或维护者的文档可以省略部分基础操作，但仍应保证说明完整、准确。
适合包含以下内容：
- API 行为说明；
- 配置项含义；
- 参数说明；
- 边界条件；
- 兼容性说明；
- 维护注意事项。
示例：
该配置项会在启动参数生成前读取。若需要影响实际启动参数，应确保配置写入发生在启动流程进入参数构建阶段之前。3. 避免误判读者水平
即使文档面向高级用户，也不应故意省略关键背景。若某个步骤失败会导致明显问题，应说明失败后的表现或排查方向。
错误示例：
配置好环境后直接构建即可。推荐写法：
配置完成后，可以在仓库根目录运行 `dotnet build` 检查环境是否可用。若构建失败，应优先检查 SDK 版本、依赖恢复情况和本地网络环境。四、术语与称谓
1. 使用标准称谓
文档中应使用统一、准确的标准称谓。涉及具体项目时，应以该项目的官方名称为准。
| 推荐写法 | 不推荐写法 |
|---|---|
| PCLC Docs | PCLC文档、这个文档站 |
| PCL Community | PCL社区、PCL 群体 |
| PCL CE | pclce、社区版启动器 |
| Minecraft | 我的世界、MC |
| Java | java |
| Mojang | mj、mojang |
| Microsoft | 微软账号体系相关场景中不应写作 ms |
| Pull Request | PR 可在首次说明后使用 |
| GitHub | github、Github |
若页面标题或上下文需要使用中文解释，可以在首次出现时写作：
Mod（通常也称为模组）之后应在同一页面内保持一种写法，不应频繁混用。
2. 使用准确的软件和项目名称
涉及具体项目时，应根据语境使用准确称谓。
- 指代 PCL Community 整体时，应使用
PCL Community。 - 指代文档站点时，应使用
PCLC Docs。 - 指代具体项目时，应使用该项目的正式名称，例如
PCL CE。 - 指代某个项目的界面或功能时，可以使用项目正式名称，也可以在上下文明确时使用“该项目”“启动器”“工具”等描述。
- 若界面中实际显示的名称与项目正式名称不同，可以在操作说明中使用界面原文。
示例：
打开 PCL CE，进入“设置 → 启动器”页面。示例：
在 PCLC Docs 中新增页面时，应确认该页面属于正确的项目目录。若必须引用界面原文，应保持界面文本一致：
点击“新建档案”按钮。3. 避免非标准缩写
除非是项目中已经广泛使用且不易产生歧义的缩写，否则不应自行缩写专有名词。
错误示例：
进入 pclce 的设置页，如果没有安装 64 位 java，最多就只能分配 1G 内存。推荐写法：
进入 PCL CE 的设置页。如果没有安装 64 位 Java，最多只能分配 1G 内存。4. 数字与单位
数字、单位和版本号应保持清晰。
推荐写法：
64 位 Java
1G 内存
Java 17
Minecraft 1.20.1同一页面中应避免混用不同写法，例如不应同时出现 1G、1 GB、1GB。若无特殊原因，优先沿用对应项目界面中的写法。
五、中文、英文与空格
1. 中英文之间应添加空格
中文与英文、数字之间通常应添加半角空格。
错误示例：
进入PCLC Docs后，选择对应项目文档。推荐写法：
进入 PCLC Docs 后，选择对应项目文档。错误示例：
安装64位Java后可以分配更多内存。推荐写法：
安装 64 位 Java 后，可以分配更多内存。2. 中文标点外侧通常不加空格
中文标点与中文之间不应额外添加空格。
错误示例：
打开设置 ， 然后选择启动器 。推荐写法：
打开设置，然后选择启动器。3. 中文引号与外部文字的连接
中文引号与外部中文文字之间通常不添加空格。
推荐写法：
点击“开始安装”按钮。如果引号内为英文界面文本，仍应根据句子结构保持自然排版。
推荐写法：
点击“New pull request”按钮。4. 使用中文标点
中文文档中应优先使用中文标点符号。
| 推荐写法 | 不推荐写法 |
|---|---|
| ， | , |
| 。 | . |
| ： | : |
| ； | ; |
| （） | () |
| “ ” | " " |
错误示例：
打开 PCL CE 的设置页, 如果没有安装 64 位 Java, 最多只能分配 1G 内存.推荐写法：
打开 PCL CE 的设置页，如果没有安装 64 位 Java，最多只能分配 1G 内存。5. 代码、命令和路径使用半角符号
代码、命令、路径、URL、配置键等技术内容应使用半角符号，并放入行内代码或代码块中。
推荐写法：
在仓库根目录运行 `pnpm install` 安装依赖。推荐写法：
图片应放入 `public/contents/` 目录。六、页面结构规范
1. 标题层级
每篇文档应只有一个一级标题，即页面标题。
推荐结构：
# 页面标题
## 一、一级章节
### 1. 子章节
#### 更细的说明不应跳级使用标题。例如，不应在 ## 后直接使用 ####。
2. 标题应描述内容
标题应准确概括该章节内容，不应使用过于口语化或含糊的标题。
不推荐：
## 一些东西
## 注意一下
## 其他推荐：
## 准备工作
## 安装步骤
## 常见问题3. 教程类页面结构
教程类页面应按照读者实际操作顺序组织内容。
推荐结构：
# 页面标题
简要说明本文用途、适用对象和适用项目。
## 一、准备工作
说明开始前需要准备什么。
## 二、操作步骤
按实际顺序说明操作。
## 三、验证结果
说明如何确认操作成功。
## 四、常见问题
列出常见错误和解决方法。4. 规范类页面结构
规范类页面应优先按规则类别组织内容，而不是按操作流程组织内容。
推荐结构：
# 页面标题
说明规范适用范围。
## 规范用语说明
解释“必须”“应”“建议”等用语。
## 基本要求
列出通用规则。
## 分类规范
按内容类型列出具体规则。
## 附录
放置标准、参考链接或补充材料。5. API 或开发者文档结构
API 或开发者文档应优先说明概念、类型、参数、行为和边界条件，不应写成普通用户教程。
推荐结构：
# API 名称
说明 API 用途和适用范围。
## 概览
列出核心概念。
## 类型定义
说明类型、参数和返回值。
## 行为说明
说明调用效果和边界条件。
## 示例
提供必要代码示例。七、段落与列表
1. 段落应完整表达意思
正文段落应使用完整句子，不应只堆叠短语或关键词。
不推荐：
打开设置。
选择 Java。
自动搜索。
完成。推荐：
打开项目的设置页面后，进入 Java 管理相关选项。点击“自动搜索”后，程序会扫描本机可用的 Java，并将搜索结果显示在列表中。2. 列表用于整理并列信息
列表适合用于展示并列事项、检查清单或步骤，但不应替代必要说明。
不推荐：
## 准备工作
- Java
- 网络
- 账号推荐：
## 准备工作
开始前，请确认本机已经安装可用 Java，并且网络环境可以访问需要下载的资源。如果需要登录特定服务，还应提前准备对应账号。3. 步骤列表应有明确动作
步骤列表中的每一项应说明具体操作，不应只写界面名称。
不推荐：
1. 设置
2. Java
3. 搜索推荐：
1. 打开对应项目，进入“设置”页面。
2. 在侧边栏中选择“Java 管理”。
3. 点击“自动搜索”，等待程序扫描本机 Java。4. 避免过长列表
如果列表项过多，应考虑拆分为多个小节，或改为表格。
一般情况下，同一组列表不建议超过 10 项。若超过 10 项，应检查是否需要重新分组。
八、提示块与警告块
文档中可以使用 VitePress 支持的提示块突出重要信息。提示块应服务于正文说明，不应替代正文，也不应被滥用。
PCLC Docs 中应优先使用 VitePress 默认支持的提示块类型：
| 类型 | 用途 |
|---|---|
info | 用于补充说明背景、限制或上下文信息 |
tip | 用于提供有帮助但非必要的建议 |
warning | 用于提醒可能导致失败、异常或误操作的情况 |
danger | 用于强调可能造成严重后果、数据丢失或不可逆影响的操作 |
details | 用于折叠较长的补充说明、示例或可选内容 |
1. info
info 用于说明背景、限制或补充解释。该类型适合放置读者需要了解，但不一定影响后续操作的信息。
::: info 说明
该设置只影响当前项目配置，不会修改系统环境变量。
:::说明
该设置只影响当前项目配置，不会修改系统环境变量。
2. tip
tip 用于补充有帮助但非必要的信息，例如推荐做法、效率提示或可选操作。
::: tip 提示
如果你不确定应该选择哪个 Java，可以优先使用程序自动搜索到的推荐项。
:::提示
如果你不确定应该选择哪个 Java，可以优先使用程序自动搜索到的推荐项。
3. warning
warning 用于提醒可能导致失败、异常或误操作的情况。读者通常需要在继续操作前理解该提示。
::: warning 注意
修改该选项后，可能会导致已有配置无法正常使用。请确认理解其影响后再继续。
:::注意
修改该选项后，可能会导致已有配置无法正常使用。请确认理解其影响后再继续。
4. danger
danger 用于强调可能造成严重后果的操作，例如数据丢失、配置损坏、无法恢复的修改等。
::: danger 危险
删除该目录会移除其中的所有本地配置和缓存文件。执行前请确认已经备份需要保留的内容。
:::危险
删除该目录会移除其中的所有本地配置和缓存文件。执行前请确认已经备份需要保留的内容。
5. details
details 用于折叠较长的补充内容。适合放置不影响主流程阅读，但在特定情况下可能有用的说明、示例或排查信息。
::: details 查看更多说明
这里可以放置较长的补充说明、命令示例或排查步骤。
:::查看更多说明
这里可以放置较长的补充说明、命令示例或排查步骤。
6. 不应滥用提示块
若普通正文已经可以清楚说明，不应额外使用提示块。
不推荐：
::: tip
点击按钮即可继续。
:::推荐写法：
点击“继续”按钮后，程序会进入下一步配置流程。提示块中也不应放置过长的主要流程。若某段内容是读者必须阅读的正文，应直接写入普通段落或独立章节，而不是放入提示块中。
九、代码块与命令
1. 代码块应指定语言
代码块应尽量指定语言，以获得正确的语法高亮。
推荐写法：
```cmd
dotnet build
``````yaml
name: CI Check
```2. 不支持的语言应使用相近语言
若站点高亮器不支持某种语言，应使用语法相近的语言。
例如，XAML 可以使用 xml：
```xml
<Grid>
<TextBlock Text="Hello" />
</Grid>
```3. 命令应注明运行位置
如果命令必须在特定目录执行，应在代码块前说明。
推荐写法：
在仓库根目录运行以下命令：pnpm install4. 命令示例不应包含无关输出
除非需要解释报错信息，否则命令代码块中只应保留命令本身，不应混入大量终端输出。
十、图片规范
1. 图片应服务于说明内容
图片应放在相关步骤附近，不应集中堆放在页面末尾。
不推荐：
## 图文示例
推荐：
1. 打开对应项目，点击“新建档案”。
2. 选择“第三方验证”，然后点击“确认”。
2. 图片描述应具体
图片的替代文本应说明图片内容，不应只写“图片”。
不推荐：
推荐：
3. 图片路径
文档图片应放在站点约定的资源目录中，并使用以 /contents/ 开头的路径引用。
推荐写法：
4. 避免过度依赖图片
图片只能辅助说明，不能代替正文。即使图片无法加载，读者也应能通过正文理解基本操作。
不推荐：
按图操作即可。推荐：
在“角色管理”页面中点击“添加新角色”，然后在弹出的窗口中输入角色名。十一、链接规范
1. 站内链接
链接到站内其他文档时，应优先使用相对路径。
推荐写法：
[技术规范](./guidelines.md)2. 外部链接
链接到外部网站时，应使用完整 URL，并确保链接来源可靠。
推荐写法：
[GitHub Pull Requests](https://github.com/PCL-Community/docs.pclc.cc/pulls)3. 链接文本应说明目标
链接文本应描述目标内容，不应使用“点击这里”“这个页面”等含糊表达。
不推荐：
详情请看[这里](./guidelines.md)。推荐：
详情请参见[技术规范](./guidelines.md)。4. 避免无依据外链
除官方文档、项目仓库、标准页面和必要参考资料外，不应随意添加来源不明的外部链接。
十二、示例写法
1. 示例应真实、简洁、可理解
示例应尽量贴近实际使用场景，不应使用容易造成误解的虚构内容。
推荐写法：
进入项目的设置页面后，如果没有安装 64 位 Java，程序可能无法分配较高内存。2. 错误示例与推荐写法
需要说明格式或表达差异时，可以使用错误示例和推荐写法。
推荐格式：
错误示例：
```text
进入pclce的设置页,如果没有安装64位java,最多就只能分配1G内存.
```
推荐写法：
```text
进入 PCL CE 的设置页，如果没有安装 64 位 Java，最多只能分配 1G 内存。
```3. 不应使用冒犯性或攻击性示例
示例中不应包含攻击、嘲讽、歧视、引战或可能冒犯读者的内容。
十三、时效性内容
1. 避免使用相对时间
文档中不应使用“今年”“最近”“目前新版”等相对时间表达，除非页面会持续维护并明确标注更新时间。
不推荐：
今年 Mojang 更新了新的版本。推荐：
Mojang 在 2024 年发布了对应版本。2. 标注适用项目和版本
涉及项目差异或版本差异时，应说明适用项目和适用版本。
推荐写法：
该功能适用于 PCL CE 2.9.0 及以上版本。推荐写法：
本文仅适用于 PCL CE，不适用于 PCL Community 维护的其他项目。若不确定具体版本，不应强行编写版本范围。可以改为说明现象或提醒读者以实际界面为准。
3. 谨慎编写临时性内容
临时活动、短期公告、临时故障绕过方案等内容不宜写入长期文档。若确有必要，应明确标注适用时间和失效条件。
十四、内容维护要求
1. 修改旧页面时应顺手修正明显问题
修改旧页面时，如果发现明显错别字、失效链接、错误称谓或格式问题，可以一并修正。
但若修正范围较大，应单独提交或在 Pull Request 描述中说明，避免影响审核。
2. 不应无意义重排全文
不应仅因个人偏好对已有页面进行大规模重排、重写或格式化。
若页面确实需要重新整理，应说明重写原因，例如：
- 原页面结构混乱；
- 步骤顺序不符合实际操作流程；
- 内容明显过期；
- 图片与正文严重脱节；
- 多处表述不符合本文规范；
- 页面内容已经不符合当前项目定位。
3. 保持页面长期可维护
新增页面时，应考虑后续维护成本。若内容依赖外部服务、第三方界面或特定版本行为，应尽量减少不必要的细节绑定，并在必要处说明适用范围。
若页面仅适用于某个项目，应在页面开头或相关章节中明确说明。不要让读者误以为该内容适用于 PCLC Docs 下的所有项目。
十五、参考标准
文档中的标点符号、中文夹用英文、格式细节应遵循以下标准和参考资料：
- 《中华人民共和国国家标准——标点符号用法》（GB/T 15834-2011）；
- 《中华人民共和国新闻出版行业标准——中文出版物夹用英文的编辑规范》（CY/T 154-2017）；
- 维基百科——格式手册。
其中，标点符号和中文夹用英文的相关要求为强制要求。若本文规范与上述标准存在未覆盖的细节，应优先参考上述标准。