群文档编辑指南

作为被移除内容的补充：协作者以外的各位，可以在群内或 GitHub 上提出建议；如有意愿获取编辑权限，请联系 @PumpkinJui，并阐述你获取权限的理由。

关于本文档及核心概念

本文档用于规范群文档编辑的细枝末节，并对编辑提出指导，旨在使群文档风格高度一致化。本页面中的所有条目均被称为「规范」。

根据国家标准的分类，我们将规范分为以下三个等级 (tier)：

1. 强制性：必须遵守的规范。如果不遵守，可能会对群文档产生较大程度的破坏；相关修改会被处理，严重的可以暂停或剥夺协作者权限。
2. 推荐性：应当遵守的规范。如果不遵守，可能会对群文档产生一定程度的破坏；相关修改可能会被处理。
3. 指导性：建议遵守的规范。不遵守也不会发生什么事，但是为了整体效果，最好遵守一下。

这里的「处理」，包括但不限于撤销更改、进一步更改、rebase 等。

如无说明，所有规范在非关键页面均为指导性，在关键页面均为推荐性。相应说明会在相应块的第一行使用粗体指出。

关键页面包括：

• 所有 README 页面
• 群文档根目录下的页面
• docs/ 根目录下的页面

作为外部资料，MCW 格式指导 为推荐性规范。

关于 Git 和 GitHub

协作者须知 (强制性规范)

以下内容为强制性规范。

无法访问 GitHub？请参阅这里。但是要注意……

如无特殊情况，禁止使用 GitHub 网页版进行大量编辑！！！

这里的大量编辑指的是单次修改单个文件以外的编辑，也即会在网页端产生多于一个 commit 的编辑。

GitHub 网页版访问缓慢，一次只能修改一个文件，且难以修改文件目录结构，严重影响 commit 列表的可读性！

推荐使用 Git 进行编辑。GitHub 桌面版客户端和 Visual Studio Code 亦可作为替代。

使用 Git

关于 Git 的使用，请参考以下文档：

• Git Documentation (官方)
• 廖雪峰的 Git 教程 (推荐)

关于 pull

以下内容为推荐性规范。

这篇文章正文和评论区的内容，对于 commit 列表维护具有很高的使用价值，请通读。

• 从「原子化」提交到妙用 rebase，一次搞定清爽的 Git 提交记录

提要：

• 每个 commit 只做一个任务；
• 在不改动远程端 commit 列表的前提下，使用 rebase 制造干净的 commit 列表。

对于长久以来的 pull 问题，现有的最佳解决方案是在 commit 前进行一次 pull。在 VSC 中，应当有一个选项叫作「Sync」，就是 pull + push。

次佳解决方案，是在 pull 时设置 --rebase：

git pull --rebase

这会在远程与本地在同一分支上分叉 (远程有本地没有的修改，本地也有远程没有的修改，进而 push & pull 都动不了) 时，通过 pull 将本地修改「变基」到远程修改以后 (这样就能 push 了)，从而让所有人都满意。

如果需要设为全局默认操作，可以使用以下命令：

git config --global pull.rebase true

在此以后，直接执行 git pull 便相当于 git pull --rebase。

这会带来一个问题：如果有未提交的修改，将会无法执行 pull。此时，可以在以上基础上增加 --autostash，或者 (反正搞了这么多就是为了这个) 先进行 commit，再 pull。

对于前者，鉴于这实在太长，可以使用 Git 别名来完成以上所有，且无须将 rebase 设为默认操作：

git config --global alias.autopull "pull --rebase --autostash"

在此以后，执行 git autopull 即相当于 git pull --rebase --autostash。你也可以通过更改命令改成任何你喜欢的名字。

关于分支

分支是一个良好的测试工具，所属的内容将会在推送后部署在 https://{branch}.groupdocs.pages.dev。

以下内容为强制性规范。

以下分支含有永久内容，是群文档的不同部分，禁止删除或互相合并：

• main
• anno

关于 GitBook

迁移

我们已经敲定，将会在 2025 年 12 月 31 日前，从 GitBook 迁移到 Docusaurus。

你可以在此页面预览迁移后的页面效果。迁移正在群文档分支进行。

此方案代号为「小恐龙」，取自上方第一个预览页面中的「Dinosaurs are cool」。也用「小恐龙」代称 Docusaurus。

目录结构

可以在以下两非官方文档中了解 GitBook 的目录结构：

• GitBook 文档（中文版） by chrisniael
• GitBook 文档 by zhaowenyu

需要注意的是，两份文档均久未更新；由于 gitbook-cli 亦久未更新，其中大部分内容可以参考，但某些关于 GitBook.com 一类的内容则可能已经过时。
另外，两份文档的访问速度可能较慢，如遇加载不出，请耐心等待。

MarkDown 语法

GitBook 使用的 MarkDown 方言类似于 GitHub Flavored Markdown (GFM, Spec)，但又与之不尽相同。你可以在 Markdown 中查看官方说明。
部分原因是，说明原文在 GitHub 上的最后一次编辑位于 16/03/17，这意味着 gitbook-cli 的 MarkDown 语法，在此之后再未发生过变化；而最新版 GFM (0.29-gfm) 更新于 19/04/06。

搭建测试

群文档内有 GitBook-cli 环境配置教程，分 Windows 和 Termux 两个版本。

markdownlint

以下内容为推荐性规范。

群文档中的文件，一般不得在已有配置下，在 markdownlint 中检出错误。
如确实需要，应在相应文本块前禁用 markdownlint 的相应规则，并在该文本块后重新启用 (操作方式见官方说明)。
禁用规则，应在简便的前提下最小化范围。

已有配置位于群文档根目录。

部分不作格式规范、无须遵守此条标准的文件及文件夹如下，以仓库根目录为相对路径：

• 文件夹：node_modules
• 文件夹：resources
• 文 件：archives/markdown.md

在群文档根目录，也有一个 Linux 脚本 专用于检查。

关于 AI

以下内容为强制性规范。

我们已经了解 AI 在当下的实用程度。但为了群文档的整体质量，我们不允许直接粘贴 AI 的输出而不进行修改或测试。

直接粘贴是省事和不负责任的举动。最起码，这些输出应当被仔细阅读或实际测试，并对其中过时或不合适的内容进行修改。

对于来自 AI 的内容，除非有特殊情况，否则应当做出来源标注，说明哪部分来自什么 AI 模型。

盘古之白

何谓「盘古之白」？

摘自给你的 Markdown 挑挑刺——语法检查器入门与进阶 | 少数派：

中英文之间加入空隙，是为了实现视觉上的区隔，更加美观和易读。理想情况下，这种「空隙」应当由排版引擎自动加入，宽度宜为 1/4 个全角空格（em）。但由于数字排版环境复杂多变，在大多数时候（包括最常见的网页环境）不能指望排版引擎有这种能力，因此只能退而求其次，手动插入一个半角空格（因其宽度通常接近于 1/4 em），达到类似效果。

什么时候添加「盘古之白」？

基本按此博客文章进行处理。例外情况如下：

• 链接以中文形式显示时无需添加盘古之白，如「一个示例网站」。但「一个 example 网站」仍需要。
• 对于 @，如果是借助该符号提及某个成员，则应当将 @xxx 作为一个整体添加盘古之白，即使该成员使用中文昵称；其他情况下单独为 @ 添加盘古之白。
• 在 GitHub 上，一些文字效果在没有盘古之白时不会正常生效。准确地说，其实是没有空格时。如删除线 ~~、斜体 *、粗体 ** 或这几种混用，在其中一端或两端临近标点符号时，会有非常奇怪的渲染方式，有时无法正常渲染出文字效果。GitBook 渲染不受此影响，但为了便于兼容还是建议加上。
• 在 MarkDown 语法中，一些文字效果在有盘古之白时不会正常生效。如斜体 * 和粗体 ** 所包裹的文字内侧如有盘古之白，则会显示为星号，而不是产生斜体或粗体效果。

直角引号

为避免引号的「弯与直」和「中文还是英文」等问题，推荐使用直角引号。

• 「弯与直」：弯引号 “”‘’ 与直引号 "' 之争。它们的码位按顺序分别为：U201C U201D U2018 U2019 U0022 U0027。
• 「中文还是英文」：引号是中文符号还是英文符号之争。影响「盘古之白」的添加。
• 「盘古之白」：难以判断是否应添加「盘古之白」，因为某些字体会把弯引号渲染为半角效果，某些则是全角。

直角引号为 「」，码位为 U300C U300D。

括号

有两种括号可以使用：

• 全角括号 （），码位为 UFF08 UFF09。
• 半角括号 ()，码位为 U0028 U0029。

对括号的使用不作要求，凭个人喜好决定；但半角括号需注意适配盘古之白。

引用 (群成员)

在一篇文章中的第一次出现，使用 @{成员昵称} 引用。此后仅使用成员昵称。

对于前者，应当将作为一个整体添加盘古之白，即使该成员使用中文昵称；同时也可以作为一个整体加粗，即 **@{成员昵称}**。后者按一般情况添加盘古之白即可，且一般不予加粗。

引用 (对群文档其他内容的引用、图片插入等)

请尽量使用 MarkDown 格式 [描述](链接) 及 ![描述](图片链接)。请务必填写描述内容。

引用互联网文章时，请写全网址 (包含 https://)。如网页支持，请填写 HTTPS 而非 HTTP。

在链接位置填写文件（相对）路径，可实现对群文档其他文件的引用。

需要注意，填写文件路径时不可填写绝对路径！如果路径以某个盘符或者 / 开始，那就是绝对路径。这样的路径在你的设备上可能运行良好，但无法被其他设备及服务器识别！

引用图片时，请将图片以最高清晰度下载，移动至群文档的 assets 目录下，按照对应文档名重命名后，使用文件路径进行引用。相同用途的图片应当只有一个名称，不要因为图片内容更新 (比如地铁图) 就把图片名跟着改来改去的；想写版本号请去文档里面写。

链接中有中文的请进行转义。这类情况最好避免掉，因为它可能导致各种各样的问题出现。

图片压缩

参考 @祉语 的建议，大多数图片会通过压缩减少大小，以优化加载速度，并减小仓库体积。

图片压缩由 @PumpkinJui 自行操作。原图片仍在 groupdocs-images 仓库可用。

不被压缩的图片包括：

• 压缩后会影响协作的，如地铁图
• 已经被 QQ 压扁了的，如群公告配图
• 原图片不清晰的
• 压缩会过度影响图片清晰度的
• 要求高质量图片的
• 压缩后比压缩前还大的
• 其他一些特殊情况