群文档编辑指南
本页面用于规范群文档编辑的细枝末节，并对编辑提出指导，旨在使群文档风格高度一致化。如无说明，所有内容均为推荐性标准。
如果你真的不想读这页东西或者认为过于麻烦，可以写好以后让我调格式。
如何作出贡献
如何编辑 (协作者须知!)
无法访问 GitHub？请参阅这里。但是要注意……
如无特殊情况，禁止使用 GitHub 网页版进行编辑！！！
GitHub 网页版访问缓慢，一次只能修改一个文件，且难以修改文件目录结构，严重影响 commit 列表的可读性！
推荐使用 Git 进行编辑。GitHub 桌面版客户端和 Visual Studio Code 亦可作为替代。
关于 GitBook
目录结构
可以在以下两非官方文档中了解 GitBook 的目录结构：
需要注意的是，两份文档均久未更新；由于 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 的相应规则，并在该文本块后重新启用 (操作方式见官方说明)。
禁用规则，应在简便的前提下最小化范围。
已有配置位于 群文档 GitHub 仓库的根目录。
部分不作格式规范、无须遵守此条标准的文件及文件夹如下，以仓库根目录为相对路径：
- 文件夹：anno
- 文件夹：logs
- 文件夹：node_modules
- 文 件：archives/markdown.md
- 文 件：docs/How-To-Ask-Questions-The-Smart-Way.md
盘古之白
所有群文档页面都应该适配「盘古之白」。
何谓「盘古之白」？
摘自给你的 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。
在链接位置填写文件（相对）路径，可实现对群文档其他文件的引用。规则为：
<name>指一个文件或一个文件夹。对于一个文件，它指文件名.后缀名，且后缀名不可省略。- 同级目录是正在编写的文件所在的目录，上级和下级目录则是相对于同级目录而言的。下级目录是同级目录下的目录，也可称为「子文件夹」。上级目录反之。
- 同级目录下的文件：
./<name>，./可省略。如./a.md和a.md都表示同级目录下的文件 a.md。 - 上级目录下的文件：
../<name>。如../a.md表示上级目录下的文件 a.md。 - 下级目录下的文件：
文件夹名/<name>。如files/a.md表示下级目录 files 下的文件 a.md。 叠加使用：三者可以相互叠加。如以下都是成立的：
- ../../a.md
- ../files/a.md
- files/web/a.html
但是
././不成立。
需要注意，填写文件路径时不可填写绝对路径！如果路径以某个盘符或者 / 开始，那就是绝对路径。这样的路径在你的设备上可能运行良好，但无法被其他设备及服务器识别！
引用网络图片时，请将网络图片以最高清晰度下载，移动至群文档的 assets 目录下，使用文件路径进行引用。最好自行重命名，以防止路径过长。
链接中有中文的请进行转义。这类情况最好避免掉，因为它可能导致各种各样的问题出现。
图片压缩
参考 @祉语 的建议，大多数图片会通过压缩减少大小，以优化加载速度，并减小仓库体积。
图片压缩由 @PumpkinJui 自行操作。原图片仍在 groupdocs-images 仓库可用。
不被压缩的图片包括：
- 压缩后会影响协作的，如地铁图
- 已经被 QQ 压扁了的，如群公告配图
- 原图片不清晰的
- 压缩会过度影响图片清晰度的
- 要求高质量图片的
- 压缩后比压缩前还大的
- 其他一些特殊情况