format-docs

格式化文档

通过 orbit confluence publish 准备 Markdown 文档，以便在 Confluence 中清晰发布。此技能会分析并转换 Markdown 文件（单个文件或整个目录树），使其符合 Confluence 的要求。

适用场景

• 首次对文档目录运行 orbit confluence publish 之前
• 向已发布的文档目录树添加新的 Markdown 文件时
• 文档在 Confluence 中显示效果不佳，需要调整结构时
• 从其他系统迁移文档时（如 GitHub wiki、Notion 导出等）

流程

1. 评估范围

确定用户询问的是单个文件还是整个目录。

• 单个文件：读取文件，并应用下方的文件级检查。
• 目录：列出完整目录树，然后逐项完成目录级和文件级检查。

2. 目录级检查

如果要格式化目录，请验证并修复以下结构问题：

INDEX.md 文件 — 每个包含 Markdown 文件的目录都需要一个 INDEX.md。此文件会成为 Confluence 中所有同级 .md 文件的父页面。

docs/
  INDEX.md              ← Required: parent page for docs/
  overview.md
  api/
    INDEX.md            ← Required: parent page for api/
    endpoints.md

如果缺少 INDEX.md，请创建一个，包含：

• Frontmatter（标题取自目录名称，日期使用今天的日期）
• 简短的介绍
• 属性报告指令（见下文）
• 用 Confluence 忽略块包裹的子页面表格

INDEX.md 结构 — 每个 INDEX.md 都必须遵循以下模式：

---
title: "Section Title"
# ... full frontmatter ...
confluence_labels:
  - my-label
---

# Section Title

> Brief intro summarizing the section.

---





## Subsection Name

| Document | Version | Summary |
|----------|---------|---------|
| [Child Page](./child-page.md) | v1.0 | Brief description |

INDEX.md 文件的主要规则：

1. 属性报告指令 — 在介绍内容后添加一个 `` 指令。此指令会在 Confluence 上生成动态表格，从所有具有相同标签的子页面提取元数据。使用 ancestor = currentContent() 限定子页面范围，并匹配 confluence_labels 中的标签。
2. Confluence 忽略块 — 将所有子页面列表内容（章节标题、表格、链接）放在 和 之间。此内容仅在 Markdown 查看器（GitHub、本地）中可见；在 Confluence 上，属性报告会取代它。
3. 标签对齐 — CQL 查询中的 label 值必须与子页面 frontmatter 中定义的某个 confluence_labels 相匹配。所有同级页面使用相同的标签，以便报告收录全部页面。
4. 报告标题 — 至少包含：Owner,Status,Version,Reviewed on。这些字段必须与子页面 confluence_properties 中的字段名称相匹配。

文件命名 — 重命名可能导致 URL 问题的文件：

• 使用小写字母和连字符：api-reference.md，而不是 API Reference.md
• 文件名中不得包含空格、下划线或特殊字符
• 文件名中不得包含版本号；改在 frontmatter 中记录版本

扁平嵌套 — Confluence 页面树最适合在根目录下仅有一层主题目录。如果目录中存在深层嵌套的子目录（3 层或更多），建议将其扁平化。

3. 文件级检查

对每个 Markdown 文件，检查并修复以下内容。有关每项规则的详细说明，请参阅格式化参考。

Frontmatter

每个文件都需要填写完整所有标准字段的 YAML frontmatter。Frontmatter 是文档元数据的唯一真实来源——frontmatter 中已有的任何元数据都不得在文档正文中重复。

始终使用完整的 frontmatter 模板：

---
title: API Reference
subtitle: "Reference — Project Docs v1.0"
date: "2026-03-09"
author: "Engineering Team"
confluence_ignore: false
confluence_labels:
  - api
  - reference
confluence_properties:
  - id: status
    fields:
      Owner: "Engineering Team"
      Classification: Internal
      Status: "{status:Green|Published}"
      Version: v1.0
      Reviewed on: 2026-03-05
---

添加或补全 frontmatter 时：

• 如果存在第一个 # heading，则据此生成 title；否则根据文件名生成
• 将 date 设为今天的日期
• 如果存在行内元数据，则据此生成 author；否则参考现有同级文件或询问用户
• 根据文档上下文生成 subtitle（例如，"ADR — Project v1.0"、"Guide — Team Docs"）
• 根据目录名称和内容建议 confluence_labels
• 始终包含 confluence_properties，至少包含：Owner、Classification、Status、Version 和 Reviewed on
• 如果文档正文中存在行内元数据，则据此填写属性值
• 默认将 confluence_ignore: false。仅当用户明确要求将文件排除在 Confluence 发布之外时才设为 true（此前发布的页面将在下次同步时被删除）
• 切勿覆盖现有的 confluence_page_id 或 confluence_url

移除冗余的行内元数据

填充 frontmatter 后，移除文档正文中与 frontmatter 或 confluence_properties 已记录信息重复的行内元数据块。这些块通常位于文档顶部附近，格式为粗体键值行或小型表格。

需要检测并移除的格式：

**Document Version**: 1.0
**Status**: Draft (Proposal)
**Classification**: Internal
**Last Updated**: March 7, 2026
**Author**: Engineering Team
**Owner**: Platform Team

还需检测并移除以下形式的元数据：

• 键值行：Version: 1.0 或 Status: Draft
• 带有元数据类标题的小型两列表格（例如，| Field | Value |）
• 引用块元数据：> **Version**: 1.0

移除规则：

• 仅移除那些信息已记录在 frontmatter 字段或 confluence_properties 字段中的元数据行/块
• 如果行内元数据块包含尚未写入 frontmatter 的值，先将其补充到 frontmatter，再移除该块
• 保留周围内容——只删除元数据行本身
• 如果元数据块后面紧跟空行或水平线，也要移除分隔符，以免留下多余空白

标题层级

转换器会跳过第一个 # heading（因为 Confluence 会使用页面标题），因此文档正文应使用 ## 作为顶层章节标题。

修复以下问题：

• 存在多个 # 标题——只保留第一个（它将作为标题），将后续的 # 改为 ##
• 标题层级缺失——不要从 ## 跳到 ####。补全层级
• 没有 # 标题——如果文件没有 # 标题，但 frontmatter 中有 title，则无需处理。如果两者都没有，则根据文件名添加一个 # 标题

文档结构

结构良好的文档遵循以下模式：

# Title

> One-line summary of what this document covers.



## Table of Contents

1. [Section One](#section-one)
2. [Section Two](#section-two)



---

## Section One

Content...

---

## Section Two

Content...

应用以下结构改进：

• 如果文档包含 3 个或更多章节（## 标题），则添加目录。使用 / 指令包围目录章节（标题 + 列表），以便发布时替换为 Confluence 目录宏。Markdown 目录在 GitHub/本地渲染器中仍会显示
• 在主要章节之间添加水平线（---），以增强视觉区分
• 如果标题后直接进入正文、缺少上下文，则添加摘要引用块

交叉引用

如果文件属于正在格式化的目录，则在靠近文档底部的位置添加“交叉引用”章节，链接到相关的同级文档：

## Cross-References

| Document | Relevance |
|----------|-----------|
| [Related Doc](./related-doc.md) | Brief note on why it's relevant |

使用相对路径，确保链接在本地和 Confluence 中都能正确解析。

修订历史

对于需要持续维护的文档，在底部添加修订历史表格：

## Revision History

| Version | Date | Changes |
|---------|------|---------|
| 1.0 | 2026-03-09 | Initial document |

如果文档中已有修订历史，则无需添加。

4. 内容格式

修复无法良好转换为 Confluence 的 Markdown 格式：

问题	修复方法
行内元数据块（**Status**: Draft 等）	合并到 frontmatter/confluence_properties 中，然后从正文中删除
原始 HTML 标签	替换为 Markdown 等效写法
<br> 标签	改用空行
多层嵌套列表（3 层及以上）	扁平化，最多保留 2 层
含多行单元格的表格	拆分为更简单的表格
使用相对路径的行内图片	确认路径相对于文件的位置正确
GitHub 风格的提示块（> [!NOTE]）	保持原样——转换器可以处理
MkDocs 提示块（!!! note）	保持原样——转换器可以处理

5. 图表格式

使用图表语言（mermaid、plantuml、graphviz、d2 等）的围栏代码块会在发布到 Confluence 时通过 Kroki 渲染为 PNG 图片（使用公开的 https://kroki.io，或配置文件中指定的自托管实例）。Orbit 会自动修正常见问题，但为了获得最佳效果，图表源文件应遵循以下规则。

默认使用此策略（--diagrams kroki）。另外还有两种策略，它们会影响以下规则的适用性：

策略	图表块的处理方式
kroki（默认）	所有图表语言都会通过配置的 Kroki 实例生成 PNG。以下自动修复会生效。
markdown-macro	Mermaid 会转换为 Confluence markdown 宏，由读者的浏览器实时绘制。其他所有语言都保留为代码块。不会连接 Kroki。
code-block	所有图表都保留为预格式化文本。不会进行网络调用。

使用 markdown-macro 时，不会应用以下自动修复——这些修复是针对 Kroki 渲染所用的 Mermaid 构建版本，而宏应用使用自己的构建版本（htmlLabels: true），因此标签中的 <br/> 会换行，而不是需要剥除。下文的手动修复仍然适用：它们是为了编写有效图表，而非针对 Kroki。

由 orbit 自动修复（无需手动操作，仅适用于 kroki 策略）：

• 参与者名称、注释和消息中的 <br/> 标签 → 剥除
• 参与者别名中的括号后缀：Worker (queue) → Worker - queue
• 参与者名称末尾的 () → 删除
• 冒号后的端口号：API:8000 → API
• 反向箭头：Client<<--API: msg → API-->>Client: msg

格式化文档时必须手动修复：

问题	修复方法
ASCII 框线字符（┌┐└┘│─）	转换为规范的 Mermaid/D2/PlantUML 语法
ASCII 时序图（|-- ->）	转换为使用规范箭头的 sequenceDiagram
内容类似图表但未标注语言的代码块	添加 mermaid、d2 或 plantuml 语言标签
以纯文本表示状态转换（DRAFT → ACTIVE → DEPRECATED）	转换为 stateDiagram-v2
特别大的图表（参与者 15 个以上、消息 50 条以上）	拆分为更小的图表

图表类型选择：

内容	最佳格式
请求/响应流程	mermaid sequenceDiagram
状态机	mermaid stateDiagram-v2
简单流程图	mermaid flowchart TD/LR
组件树	mermaid graph TD
实体/数据模型	mermaid erDiagram
嵌套架构	d2
分层系统	d2

格式化文档时，遇到 ASCII 艺术字或基于文本的图表，请将其转换为适当的图表语言。如果无法确信能够正确转换复杂图表，请将其保留为语言标签为 text 的纯代码块。

6. Confluence 专属增强

以下可选改进使用了 Confluence 功能：

• 状态徽章 — 在属性字段中使用 {status:Color|Text} 语法（例如 {status:Green|Published}）。也支持 Emoji 短代码（:green_circle: Green）。
• Confluence 忽略块 — 使用 和 包裹仅应显示在 markdown 中（不应显示在 Confluence 中）的章节。在 INDEX.md 文件中，所有子页面表格都必须用忽略块包裹（参见上文“目录级检查”）。
• 属性报告 — 每个 INDEX.md 都必须包含属性报告指令。确切格式请参见“目录级检查”中的 INDEX.md 结构。

7. 试运行

完成更改后，建议用户使用以下命令进行验证：

orbit confluence publish <directory> --space <SPACE> --parent <PAGE_ID> --dry-run -p <profile>

此操作会预览即将发布的内容，但不会实际进行更改。

规则

• 永远不要删除内容——只能调整结构并添加元数据。
• 永远不要覆盖 confluence_page_id 或 confluence_url——它们由 orbit confluence publish 管理。
• 保留现有的 frontmatter 字段——添加缺失字段，不要删除已有字段。
• 如果不确定标题，先根据 # heading 推导，再根据文件名推导。
• 尽量少改动——不要改写正文；除非标题层级有误，否则不要重组章节。
• 对大型目录进行更改前，先向用户展示更改摘要。