GitLab Flavored Markdown (GLFM) 开发指南

本页及相邻页面包含有关 GitLab Flavored Markdown (GLFM) 的开发者指南。 有关 GitLab 中 Markdown 的用户文档，请参阅 GitLab Flavored Markdown。

GitLab 在多个地方支持 Markdown，例如 issue 或 merge request 描述、评论和 wiki。 我们使用的 Markdown 实现被称为 GitLab Flavored Markdown (GLFM)。

CommonMark 是 GLFM 的核心。

…一套用于 Markdown 的标准、无歧义的语法规范，以及一套全面的测试套件，用于根据此规范验证 Markdown 实现。

来自 GitHub Flavored Markdown (GFM) 的扩展，例如表格和任务列表，是受支持的。 随后，添加了各种 扩展，例如数学公式和多行引用块，从而创建了 GLFM。

基本流程

为了生成显示给用户的 HTML，Markdown 通常按以下方式处理：

• 从用户或数据库中读取 Markdown，并将其传递给后端。
• 执行一个处理管道（即 “Banzai” 管道）。
  • 进行一些预处理，然后使用 gitlab-glfm-markdown gem（该 gem 使用 comrak）将其转换为基本 HTML。
  • 运行各种过滤器，这些过滤器会进一步转换 HTML。例如处理引用或自定义 emoji。
• 然后 HTML 被传递给前端，前端以各种方式显示它，或者将其缓存在数据库中。
  • 例如，富文本编辑器将 HTML 转换为 tiptap 使用的格式，以便进行显示和编辑。

目标

我们的目标是 GLFM 始终保持与 CommonMark 100% 的兼容性。 除非绝对必要，否则我们会非常谨慎地避免添加新的语法。 在这种情况下，应该进行研究，以找到最可接受的 “Markdown” 语法，如果存在，则严格遵循通用的实现。 CommonMark 论坛 是研究不同主题讨论的好去处。

其他资源

• GitLab Flavored Markdown
• 富文本编辑器开发指南
• Emojis
• 如何在 frontend 渲染 GitLab 风格的 Markdown？
• Diagrams.net 集成

如有任何问题，请联系 Plan:Knowledge 团队。