跳到主要内容

群文档编辑指南

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

关于本文档及核心概念​

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

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

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

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

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

关键页面包括：

  • 群文档根目录下的页面
  • 所有 README 或类似功能的页面

作为外部资料，MCW 格式指导、少数派风格指南 为推荐性规范。

关于 Git 和 GitHub​

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

以下内容为强制性规范。

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

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

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

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

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

使用 Git​

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

关于 pull​

以下内容为推荐性规范。

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

提要：

  • 每个 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
  • legacy_main
  • legacy_anno

关于 Docusaurus​

markdownlint​

以下内容为推荐性规范。

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

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

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

  • 目录：blog/anno/

在群文档根目录，也有一个 Linux 脚本 专用于检查。这意味着此脚本可以在 Termux、Git Bash 等命令行环境中执行，但不能在 cmd、PowerShell 等命令行环境中执行。在运行前，你需要先通过 Node.js 安装 markdownlint-cli2。

关于 AI​

以下内容为强制性规范。

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

直接粘贴是图省事和不负责任的举动。如果一篇文档有 90% 甚至 100% 都是 AI 写的，那要协作者干什么？

最起码，这些输出应当被仔细阅读或实际测试，并对其中错误、过时和不合适的内容进行修改。同时应当做出来源标注，至少说明哪部分来自什么 AI 模型。

关于 AI 使用的细则，请参考少数派 AI 生成内容规则（试行）。
除「审阅标准」和「责任承担和违规处理方式」外，此规则亦被视为强制性规范。

盘古之白​

何谓「盘古之白」？​

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

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

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

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

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

直角引号​

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

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

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

括号​

有两种括号可以使用：

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

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

引用块与高亮块​

Docusaurus 迁移后，我们迎来了众多新语法，其中就有高亮块。

相较作为 MarkDown 规范一部分的引用块 >，高亮块美观而具有较为灵活的写法，不需要像引用块不仅需要每行行首加 >，还得担心换行问题。

但与此同时，高亮块的语法千奇百怪。我们在：

  • Docusaurus：:::note
  • GitHub：> [!NOTE]
  • Python-Markdown (MkDocs 底层)：!!! note
  • Pymdownx (上述的扩展包)：/// admonition (linebreak) type: note
  • Notion：>，原有的引用只能在菜单找

看到了各种各样的语法，并且它们互不兼容。这导致高亮块兼容性极差。

少数派作者 @LillianWho 用 Obsidian 插件做的高亮块兼容 (语法为用 ad-note 标识语言的代码块)。TA 在文章 Admonition：生来多彩 中写道 (原文如此)：

我反对将 markdown 搞成富文本那样花里胡哨，markdown 之所以好用，就是你可以用写作的方式来排版，写完之后，排版也完成了，不需要多余做什么。不用操心字体、颜色、大小。

Admonition 在用的时候，你需要手动加代码块，然后还要对应上你设置的块类型。写完后，这个 md 文档拿到其他地方，脱离该插件，效果就会完全不对，成了普通代码块。

……

但我知道有很多同学，就是很喜欢富文本效果，喜欢那些炫酷文字和背景。这些在 markdown 中其实支持都不是很好。markdown 生来就不是干这个的。

但 Admoniton 是，它生来就对实用主义笔记没有用，它生来就是绚丽多彩，颜值高到一骑绝尘。

在上述基础上，考虑兼容、美观与省事，我们建议：

  1. 在下列条件满足其一时，宜使用引用块
    • 你确实在进行引用，且不算空行时行数少于 5 行 (以行号计数)
    • 这段内容需要在其他平台 (如 GitHub 仓库) 得到正常展示
    • 你使用的编辑器不支持高亮块渲染
    • 该文档适合使用较为严谨的风格进行叙述
  2. 在下列条件满足其一时，宜使用高亮块
    • 你确实在进行引用，但不算空行时行数大于 5 行 (以行号计数)，或其中掺杂了可能导致渲染问题的 MarkDown 语法
    • 这个块和引用没啥关系
    • 去掉该部分不影响前后文理解
    • 该文档适合使用较为活泼的风格进行叙述
  3. 如双方条件同时满足，宜按满足条件数计数并取较多一方，相同时宜使用引用块；如同时不满足，宜使用引用块
  4. 可适当考虑个人喜好因素

使用引用块时，宜在每行前均加入 > 并加空格，在需要换行的位置仅使用一个 > 并换行。例如：

> 全世界无产者，联合起来！
>
> Working men of all countries, unite!

渲染为：

全世界无产者，联合起来！

Working men of all countries, unite!

如在需要换行的位置不加只有 > 的空行：

> 全世界无产者，联合起来！
> Working men of all countries, unite!

将会被渲染为一行：

全世界无产者，联合起来！ Working men of all countries, unite!

引用 (群成员)​

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

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

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

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

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

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

需要注意，填写文件路径时不可填写绝对路径！绝对路径只能保证对当前设备有效；它在你的设备上可能运行良好，但无法被其他设备及服务器识别！

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

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

图片压缩​

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

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

不被压缩的图片包括：

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