AI Agent Engineer

AI Agent Engineer

Markdown 参考资料、版本与兼容性说明

7 min read

Markdown 参考资料、版本与兼容性说明

这篇说明解决什么问题

本库保留 Markdown 完整教程 与 Mermaid 完整教程 两篇大型参考材料，不对其做统一格式重写。大型教程适合按主题查阅，但宿主能力和上游语法会变化；本页集中记录实际核对版本、兼容边界和应优先采用的准确写法。

截至核对日的版本事实

核对日期：2026-07-14。

项目已核对事实使用时的边界
CommonMark官网最新发布规范为 0.31.2（2024-01-28）是社区维护的明确规范，不代表所有 Markdown 工具完全一致
GFM正式规范页为 0.29-gfm（2019-04-06）表格、任务列表、删除线和扩展自动链接属于 GFM 扩展
Obsidian使用 Obsidian Flavored Markdown，并提供 wikilink、embed、Properties、callout 与 Mermaid 等能力当前 vault 的实际渲染仍取决于本机版本、设置、主题与插件
Mermaid 上游官方文档页面当前显示 11.16.0 相关能力上游最新语法不等于宿主已经捆绑
Obsidian MermaidObsidian 1.13.0 更新日志说明其捆绑 Mermaid 11.13.0，并增加 vault 级 Mermaid 渲染确认不能据此推断本机正在运行 1.13.0；本库未读取或确认本机 Obsidian 版本
GitHub MermaidGitHub 文档把 Mermaid 作为平台图表功能，并提供 info 图查看其当前版本这不是 GFM 0.29-gfm 的语法扩展

版本事实只对核对日负责。复制使用新语法前，在目标宿主进行最小渲染测试。

Markdown 大型教程的兼容提醒

HTML 元素内的 Markdown

在 Obsidian 中，Markdown 语法不会继续在 HTML 元素内部解析。若在 <details> 中需要粗体，使用 HTML：

<details>
<summary>展开答案</summary>
<strong>这是 Obsidian 中可预测的粗体写法。</strong>
</details>

不要把 GitHub 或浏览器中某种混合解析结果推广到 Obsidian。更可移植的选择是把 Markdown 正文移出 HTML 容器。

Alias 不是裸链接目标

需要显示“Markdown 完整教程”时，确定性写法是实际路径加显示文字：

[[Knowledge/AI Agent Engineer/docs-CN/Markdown/Markdown 教程|Markdown 完整教程]]
 
[[Knowledge/AI Agent Engineer/docs-CN/Markdown/Markdown 教程#11. 表格|跳转到表格部分]]

不能只把 title 值或 alias 文本放在 [[...]] 左侧并假定它一定解析到真实文件。

“标准 Markdown”要说清指代

本库优先写“CommonMark 兼容语法”“GFM 扩展”或“Obsidian 专用语法”，避免暗示存在一个所有宿主都完全实现的单一标准。

Mermaid 大型教程的兼容提醒

以下准确边界应优先于大型教程中的概括性表述：

  1. 先同时检查语法和宿主：无法显示可能来自语法错误、宿主未启用、捆绑版本较旧、安全确认或权限设置，不能先断言“通常不是语法问题”。
  2. 子图方向有条件：当子图中的节点与外部节点相连时，Mermaid 官方说明该子图的 direction 会被忽略并继承父图方向。
  3. 时序箭头只定义线型和端点：-->> 是带箭头的虚线，--x 是以叉号结束的虚线；“返回”“失败”是作者赋予消息的业务语义，不是语法自动保证。
  4. 类图关系要精确：--> 是 association；..> 是 dependency。是否表示“使用”要由领域关系和标签说明。
  5. 状态图起止 token：精确写作 [*]，中间没有空格。
  6. Mindmap 仍标为 experimental：基础语法可用，但集成能力和细节可能变化，目标宿主不支持时可降级为 flowchart。
  7. GitHub 渲染不属于 GFM：GitHub 支持 Mermaid 是平台功能；可按 GitHub 文档用 info diagram 查看其当前 Mermaid 版本。
  8. 嵌套围栏必须加长外层：大型教程原“Obsidian 中的建议”示例曾用同长度围栏导致后文被吞；本轮仅把该外层修为四反引号，未改写教程内容。

宿主版本探针

GitHub 文档提供如下 info 图，用于在 GitHub 渲染器中显示其使用的 Mermaid 版本；它不是 Obsidian 的通用版本探针：

```mermaid
info
```

在 Obsidian 中应查看当前应用版本与更新日志，并用两节点最小图直接测试目标语法。不要从“官网示例可用”推断当前 vault 一定可用。

资料使用优先级

遇到冲突时按以下顺序判断：

  1. 当前目标宿主的官方文档和更新日志；
  2. CommonMark、GFM 或 Mermaid 的对应正式语法页；
  3. 本库新建的正式课程笔记；
  4. 两篇大型教程中的历史示例；
  5. 记忆、搜索摘要或未经验证的社区回答。

仍无法证明时，明确写“当前只能推断”或“未在目标版本验证”。

主要一手资料

返回 Markdown 目录。

Backlinks