贡献指南

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

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

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

快速开始

前置条件

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

贡献流程

1. Fork 并克隆仓库

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

2. 安装依赖

   在项目根目录运行：

   npm install

3. 启动本地预览

   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 文件作为该目录的索引页。索引页应列出该目录下的所有文档链接，方便用户浏览。

示例：

# 新手指南

本页面收录了 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 速查表 —— 独立的速查页面，适合学完基础后快速查阅常用语法。

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

编辑器推荐

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

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 社区贡献一份力量。无论是修正一个错别字，还是撰写完整的攻略文档，每一份贡献都会让这里变得更好。