---
url: /CONTRIBUTING.md
---
# 贡献指南

感谢你考虑为 EnderRealm 文档做出贡献！这份指南将帮助你了解如何参与文档编写与完善。

无论你是想修正一个错别字，还是撰写一篇完整的攻略，这里都会告诉你该怎么做。

如果你已经很熟悉 Markdown 和 Git 操作，可以直接跳到「编写规范」章节查看本项目特有的要求。

## 快速开始

### 前置条件

* **Node.js**（推荐 18.0 或更高版本）
* **Git**

### 贡献流程

1. **Fork 并克隆仓库**

   先将本仓库 Fork 到你的 GitHub 账户，然后将仓库克隆到本地计算机。

2. **安装依赖**

   在项目根目录运行：

   ```bash
   npm install
   ```

3. **启动本地预览**

   ```bash
   npm run docs:dev
   ```

   启动后，用浏览器访问 `http://localhost:5173` 即可看到与文档中心一致的页面。

4. **编写或编辑文档**

   按照「编写规范」章节的要求创建或修改文档。保存文件后刷新本地预览页面，确认渲染效果无误。

   如果你不熟悉 Markdown 语法，建议先阅读本文档末尾的「Markdown 编写参考」章节，再返回继续。

5. **提交并推送**

   将你的修改提交到本地仓库，并推送到你 Fork 的远程仓库。

6. **发起 Pull Request**

   在 GitHub 上你的 Fork 仓库页面，点击 **"Contribute" → "Open pull request"**，填写说明后提交。

7. **等待审核**

   维护者会对你的提交进行审核。如果有需要修改的地方，会在 Pull Request 中留言。

> **提示**：如果你只是修改一个简单的错别字或格式问题，也可以直接通过 GitHub 网页端编辑文件并发起 Pull Request，无需在本地搭建环境。但如果涉及多文件修改或新增文档，强烈建议走完整的本地预览流程。

## 编写规范

### 文档存放位置

* 所有文档**必须位于项目根目录下的中文命名文件夹中**（如 `官方规则/`、`新手指南/`、`世界探索/` 等），不允许放置在其他任何位置。
* 你可以在这些分类文件夹下自由嵌套子文件夹，形成多层级的目录结构来组织内容。
* 每一个目录（无论层级）都必须包含一个 `index.md` 文件作为该目录的索引页。这意味着每当你新建一个文件夹，就需要在其中创建 `index.md`。
* 请勿修改 `.vitepress/` 目录下的配置文件或其他非文档类文件。

### 命名规范

* 文件夹和文件名使用**中文**，例如 `新手指南/第一天生存.md`。
* **禁止使用拼音**（如 `xinshouzhinan/` 或 `diyitian.md`），拼音会让其他人难以理解文件内容。
* 避免使用空格和特殊字符。

### 内容规范

* 正文内容应使用**简体中文**撰写，确保清晰易懂。
* **禁止在正文中使用拼音替代中文**。拼音仅允许作为生僻字的注音批注出现，例如：「饕餮（tāo tiè）」。
* 英文专有名词（如 `Minecraft`、`VitePress`）以及其他语言的专有名词不受此限制，可直接使用。

### 目录索引（index.md）

每个文件夹**必须包含一个 `index.md` 文件**作为该目录的索引页。索引页应列出该目录下的所有文档链接，方便用户浏览。

示例：

```markdown
# 新手指南

本页面收录了 EnderRealm 的新手入门相关文档。

## 文档列表

- [第一天生存指南](/新手指南/第一天生存指南)
- [基础工具制作](/新手指南/基础工具制作)
- [如何寻找食物](/新手指南/如何寻找食物)
```

当你新增文档时，必须同步更新对应文件夹的 `index.md`，把新文档的链接添加进去。

### 官方文档修改须知

官方性质文档（如《玩家守则》《用户协议》等）的最终修改权归属管理组。如果你发现这类文档存在错误或需要改进，请勿直接提交 Pull Request。正确做法是提交一个 Issue，描述你发现的问题和建议，管理组会统一处理。

## Markdown 编写参考

如果你之前主要使用 Word 等排版工具，可能对 Markdown 感到陌生。这一节会帮助你快速上手。如果你已经熟悉 Markdown，可以直接跳过。

### Markdown 是什么

Markdown 是一种纯文本的标记语言。它和 Word 的本质区别在于：

* **Word** 是“所见即所得”——你选中文字，点击“加粗”按钮，它立刻变粗。
* **Markdown** 是“所写即所得”——你通过输入简单的符号来标记格式，比如用 `**文字**` 表示加粗。这些符号在原始文本中清晰可见，最终由渲染器将其转换为美观的 HTML 页面。

这意味着 Markdown 文件非常轻量、易于版本管理（Git 可以清晰追踪每一处修改），而且你只需要关注内容本身，不用纠结字体、字号、颜色等排版细节。

Markdown 的语法非常少，核心内容几分钟就能学会。它存在不同“方言”（如 GitHub Flavored Markdown、CommonMark 等），但基础语法是通用的，本文档使用的语法在 VitePress 中均能被正确渲染。

### 本文档中必须使用的基本格式

无论你写什么内容，请至少遵循以下层级结构：

#### 大标题

每篇文档有且仅有一个一级标题，用 `#` 表示，通常是文档的标题：

```markdown
# 新手指南：第一天生存
```

#### 二级标题

用于划分文档的主要章节，用 `##` 表示：

```markdown
## 前期准备
## 收集资源
## 建造庇护所
```

#### 三级标题

用于二级标题下的进一步细分，用 `###` 表示：

```markdown
### 获取木材
### 制作工具
```

标题的层级嵌套必须合理——不要从一级标题直接跳到三级标题，也不要让二级标题下只有一个孤立的段落而没有子结构。合理的层级不仅让渲染效果清晰，也让其他贡献者更容易理解和维护你的文档。

#### 正文与段落

直接书写纯文本即可。段落之间用空行分隔。需要强调时，用 `**粗体**` 包裹重要内容。

### 如何快速学习 Markdown

Markdown 的核心语法半小时内即可掌握。推荐以下资源：

* **Markdown 入门教程** —— 从首页开始阅读即是一篇完整、系统的入门教程，适合从零开始学习。
* **Markdown 速查表** —— 独立的速查页面，适合学完基础后快速查阅常用语法。

你不必一次性学完所有内容。掌握标题、段落、列表、链接、图片、粗体这六项基础语法，就已经足以编写绝大多数文档。遇到不确定的写法，随时查阅速查表即可。

### 编辑器推荐

选择一个合适的编辑器能大幅降低编写难度。

#### PC 端

* **Typora（付费）**：提供类似 Word 的“所见即所得”编辑体验，你不需要记住 Markdown 符号，输入时会自动转换显示效果。对完全不熟悉 Markdown 的新手极其友好。缺点是付费软件，但提供试用期，可以先体验再决定是否购买。
* **Visual Studio Code（免费）**：内置 Markdown 预览功能，打开 `.md` 文件后，点击编辑器右上角的预览按钮，或使用快捷键 `Ctrl+Shift+V`（Mac 上为 `Cmd+Shift+V`），即可实时预览。同时支持源代码和预览左右分屏对照编辑。适合需要项目级管理体验的用户，缺点是它需要你了解 Markdown 语法，不如 Typora 那样对新手无感。如果你未来打算频繁参与文档贡献，值得花一点时间学习使用。
* **其他免费选择**：Mark Text（开源免费，所见即所得）或 Obsidian（免费，插件丰富），它们在编辑体验上都相当成熟。

#### 手机端

手机上编辑 Markdown 相对不便，但在需要时可以这样做：

* **Obsidian（免费，提供安卓与 iOS 版本）**：支持 Markdown 实时预览和语法高亮，移动端编辑体验相当不错。可以通过同步服务与 PC 端联动，适合需要在手机上编辑的贡献者。
* 使用在线 Markdown 编辑器（如 StackEdit 或 Dillinger），在浏览器中编写内容，完成后复制内容或导出文件。
* 如果你使用 Android 手机，MT 管理器等专业文件管理器内置了文本编辑功能，部分支持 Markdown 语法高亮。虽然它不会直接渲染 Markdown，但语法高亮能帮你在编辑时发现一些明显的格式错误。完成编辑后，将文件传输到电脑上运行 `npm run docs:dev` 查看渲染效果，或者使用第三方在线渲染工具检查。

### 利用 AI 辅助转换格式

如果你实在不想手动编写 Markdown，可以将已写好的文本内容（哪怕是纯文本或 Word 文档中的内容）提供给 AI 工具，并给出明确的指令，例如：

> "请将以下内容转换为 Markdown 格式，使用合理的标题层级、列表和段落分隔。不要添加或删减任何实质内容，只做格式转换。将转换后的 Markdown 内容以代码块形式直接输出，方便我复制。"

然后把你写的原文粘贴在下方。

但请务必注意以下原则：

1. **内容以人工编写为主**。AI 适合做格式转换，但不适合替你思考要写什么。你贡献的内容应当来自你真实的经验和知识。
2. **AI 生成的内容必须逐字审查**。如果 AI 帮你转换了格式，或帮你润色了表达，你必须仔细确认：有没有多出原文中没有的信息？有没有因为理解偏差而改变原意？有没有出现事实性错误？
3. **你自己要对提交的内容负最终责任**。审核不仔细可能导致错误信息被收录进文档库，影响所有阅读者。

### 无论用哪种方式编写，请必须检查渲染效果

这是提交前不可跳过的一步。

Markdown 的语法虽然简单，但不同渲染器之间可能存在细微差异。一处看似正确的标记，在实际页面中可能显示异常。无论你用什么编辑器、什么方式编写，请在提交前至少确认一次最终渲染效果：

* **首选方式**是运行 `npm run docs:dev`，在浏览器中查看本地站点，这是最准确的预览方式。
* 如果实在无法启动本地预览服务器，至少将内容粘贴到在线渲染工具（如 Markdown Live Preview）中检查一遍，确认没有明显的格式错误。
* 如果发现渲染结果与预期不符，回到源文件检查 Markdown 语法，修改后再预览，直至确认无误。

## 关于许可协议

本项目中的文档采用双重许可，详见 README 中的完整说明。简要概括如下：

* **官方性质文档**（如规则、政策、管理公告等）：采用 **CC BY-NC-ND 4.0 协议**
* **玩家自主编写的内容**（如攻略、心得、教程等）：采用 **CC BY-NC-SA 4.0 协议**

提交贡献即表示你同意根据内容性质适用对应协议。如果你参考了其他采用 CC 协议的资料并因此产生了协议继承问题，请在提交时明确说明。

**通用原则**：以上为通用标准。若特定文档有特殊规则（如因继承上游协议而采用不同的 CC 许可），则以该文档自身的声明为准。

## 还有疑问？

如果你在贡献过程中遇到任何问题，欢迎通过以下方式联系：

* 对于一般性的疑问、建议或问题反馈，请提交 **Issue**，描述你遇到的情况。
* 对于已提交的 Pull Request 中需要讨论的具体内容，可在该 Pull Request 中直接留言。

感谢你为 EnderRealm 社区贡献一份力量。无论是修正一个错别字，还是撰写完整的攻略文档，每一份贡献都会让这里变得更好。