看到“Markdown 语法大全 - 全面测试文档”这个标题时我第一反应是语法大全不稀奇稀奇的是“测试文档”这四个字。作为常年用 Markdown 写技术文档、做知识管理、还经常要把文档转成 Word/Excel 交付给同事的人我太清楚这几个字的分量了。语法谁都会背真正难的是让你的 Markdown 在任何编辑器、任何平台、任何转换链路上渲染出来的结果都符合预期。这篇博文就想围绕“全面测试文档”这个角度把 Markdown 的核心语法、选型逻辑、实操细节和踩坑经验一次讲透适合正在系统学习 Markdown 的初学者也适合想统一团队文档规范、减少“复制过去就乱了”这类麻烦的老手参考。1. 从“语法大全”到“测试文档”Markdown 到底在解决什么问题1.1 Markdown 能火靠的是“语义优先”而不是“页面漂亮”很多人第一次接触 Markdown 都会有个共同疑问它看起来不就是纯文本加几个符号吗为什么能成为程序员、产品经理、自媒体写手都离不开的格式我的理解是Markdown 的核心贡献不是让你“排版更漂亮”而是把文档从“表现层”拉回到了“语义层”。传统 Word 文档里一个一级标题的本质是字体大小 16 磅、加粗、段前段后 12 磅换台电脑字体缺失整个版式就崩了。Markdown 里的#就单纯表达“这里是个一级标题”至于它在屏幕上显示成多大字号、什么颜色完全交给渲染器决定。这就带来一个巨大的好处同一份.md文件在 Typora、Obsidian、VSCode、GitHub 网页上打开骨架永远是一致的变的只是“皮肤”。对于需要长期维护、多人协作、多端同步的文档来说这种稳定性比美貌值钱得多。语法大全类的文章往往只做一件事把符号列出来告诉你它是什么意思。但真正决定 Markdown 使用体验的是对这套“语义优先”逻辑的理解。你知道1.开头是有序列表但你知道列表嵌套在多数渲染器里要求缩进 2 到 4 个空格缩进错了直接解析成普通段落吗你知道表格写完后在 Typora 里显示得好好的复制到 GitHub Issue 里却可能因为列数不齐整体烂掉吗这些都属于“测试文档”要回答的问题而不是“语法大全”能覆盖的。1.2 “全面测试文档”真正该验证的是渲染一致性既然叫“全面测试文档”那它的定位就不是教学材料而是一份“验收清单”。你可以把它理解成软件测试里的冒烟测试每次拿到一个新的 Markdown 编辑器、一个新的渲染平台、或者一条新的转换链路先把这份文档丢进去跑一遍看哪些语法正常工作、哪些行为异常心里就有底了。我建议所有重度 Markdown 用户都维护一份自己的测试文档至少覆盖这样几个维度标题层级是否完整、列表嵌套是否正常、代码块语言高亮是否生效、表格对齐是否保留、行内代码里出现特殊符号是否有问题、图片相对路径能否被正确解析、中文锚点和特殊字符能不能跳转、数学公式和图表扩展是否可用。每验证新环境前花 10 分钟跑一遍比遇到问题时再去查资料高效得多。我自己实际踩过的例子有一版文档在本地 Obsidian 里任务列表渲染非常正常但发给同事用 Typora 打开- [ ]直接变成了普通圆点列表后面还跟了个奇怪的方括号字符串。两个人排查了半天发现是跨平台换行符在作祟。这类问题没有测试文档你是很难提前预判的。2. 手把手搭一份可复用的全要素 Markdown 测试文档2.1 测试文档的内容结构怎么组织我在实际使用中把 Markdown 渲染元素分成三类块级元素、行内元素、扩展元素。块级元素包括标题、段落、列表、引用、代码块、分隔线、表格它们决定文档的整体骨架行内元素包括加粗、斜体、删除线、行内代码、链接、图片它们负责在段落里做局部修饰扩展元素则指那些不在原始 Markdown 规范里、但现代主流编辑器几乎都支持的语法比如任务列表、数学公式、Mermaid 图表、HTML 标签混排。测试文档的设计思路应该按这三个层级展开先验证最基础的块级和行内语法再验证扩展语法。不建议把所有语法平铺在一起写成长篇否则一旦某个地方渲染出错你很难快速定位是哪一类语法的问题。我自己习惯把每个模块单独用分隔线隔开并在每个模块开头用一段注释性质的说明文字标注“本段测试意图”这样无论是人工看还是截图对比都很直观。2.2 一份可以直接套用的测试文档模板先说结论下面是目前我在多个编辑器之间做兼容性测试时用的一个基础模板各位可以直接复制保存成一个markdown-test.md文件。# 一级标题 ## 二级标题 ### 三级标题 普通段落这里包含行内加粗 **加粗**、斜体 *斜体*、删除线 ~~删除线~~以及行内代码 const a 1。 --- - 无序列表项 - 继续 - 嵌套项缩进 2 空格 - 回到外层 1. 有序列表第一项 2. 有序列表第二项 1. 嵌套有序列表 3. 有序列表第三项 - [ ] 未完成任务 - [x] 已完成任务 引用内容 引用段落第二行 javascript function hello() { console.log(hello markdown); }左对齐居中对齐右对齐单元格单元格单元格第二行第二行第二行普通链接行尾两个空格加上回车可以实现软换行HTML 混排测试红色文字这里要特别提醒两点。第一代码块内的符号切勿省略语言标注 javascript 和 的渲染效果在大部分平台上差距很大前者会触发语法高亮后者默认是没有高亮的。第二表格建议标题栏和分隔行之间不要留空行很多渲染器对表格前后的空行解析很敏感你在这里多按一个回车表格可能就断成两截。 ### 2.3 拿到模板后怎么跑一遍“验收流程” 模板只是素材怎么用才是关键。我的习惯是三步走先在目标编辑器里打开这个文件确认显示效果然后按编辑器提供的导出能力分别导出 HTML 和 PDF检查导出版本和预览版本是否一致最后把原文件内容粘贴到目标平台GitHub Issue、团队 Wiki、公众号后台等观察同一个 Markdown 在被别人二次处理时有没有变样。 三步走的过程中我会拿一张 Excel 表格来做记录每行是一个语法模块每列是一个测试环境遇到渲染正常就打“通过”异常就写下异常内容和复现步骤。这个记录一旦积累了十个以上环境的测试结果基本就相当于一份“渲染兼容性地图”。以后同事问我“这个语法在某某平台能不能用”我不用当场猜直接查表就有答案。 ## 3. 编辑器与在线平台实测VSCode、Typora、Obsidian、GitHub 的渲染差异 ### 3.1 主流 Markdown 环境的定位差异 选编辑器之前先想清楚你的使用场景这点比纠结哪个编辑器“最强”重要得多。我用过一段时间把 Typora、Obsidian、VSCode 全部装好想找一个“完美工具”后来发现三个环境各有明确分工根本不存在谁替代谁的问题。下面这个对比是我个人高频使用后的总结 | 工具 | 核心定位 | 最强场景 | 主要局限 | | ---- | ---- | ---- | ---- | | Typora | 所见即所得写作 | 单篇长文、导出精美文档 | 偏重写作知识管理能力弱 | | Obsidian | 本地知识库 | 双链笔记、个人知识管理 | 扩展语法依赖插件 | | VSCode | 代码与文档一体化 | 开发者写技术文档 | 心智能量占用高上手有门槛 | | GitHub | 在线协作与托管 | 开源项目、Issue、Wiki | 离线不可用私人仓库渲染受限 | 说几个我实测下来的细节。Typora 的文件树和导出能力在同类工具里做得很成熟适合作为团队文档的统一编辑端。Obsidian 对本地 Markdown 文件的管理方式几乎是直觉级的它默认会把附件放到一个指定文件夹并自动把文档内的图片路径改成相对路径这点对知识库非常友好但需要注意它内置的很多“增强语法”其实是插件带来的换到其他编辑器里就会失效。VSCode 的优势在于完全开放Markdown 插件生态比另外两者丰富得多只要你愿意花时间调教它能做到几乎完美的写作体验和版本管理结合。 ### 3.2 VSCode写Markdown插件组合与内置预览技巧 如果你主要用 VSCode 写 Markdown我建议至少安装两个插件Markdown All in One 和 Markdown Preview Enhanced。Markdown All in One 解决的是写作效率问题它能一键生成目录、自动编号、格式化表格、为标题自动添加序号还支持快捷键快速插入粗体、斜体、代码块。这些能力看起来基础但累积起来能省下大量时间。Markdown Preview Enhanced 则解决的是预览和导出问题支持自定义 CSS、MathJax 数学公式、代码高亮还能把 Markdown 导出为 HTML、PDF、图片甚至可以直接打开一个浏览器窗口做实时预览。 有一个关于内置预览的点值得单独说一下新版 VSCode 的 Markdown 预览其实已经内置了对数学公式和图表的支持很多教程还在教你怎么装额外插件其实只需要在设置里把 markdown.math 和 markdown.mermaid 相关选项打开就行。这个细节特别容易踩坑——如果你明明安装了插件但图表预览不出来先检查一下是不是被内置设置拦截了。使用预览时我会开启“跟随光标”模式写完一段扫一眼渲染结果比全文写完了再统一预览要稳妥很多有问题能当场发现不用滚动半天找是哪段语法出了问题。 ### 3.3 同一份文档在不同平台渲染结果的差异清单 同一个 Markdown 文件在不同平台的渲染结果真的会不一样这不是哪家做得不好而是 Markdown 的标准本身留下了太多模糊地带。最容易感知到的差异是换行规则标准 CommonMark 语法里单次换行会被当作普通空格处理两次连续换行才会产生新段落但 GitHub 采用 GFM 规范默认把单次换行也渲染成换行。这就意味着同一份文档里如果你只按了一次回车在 Typora 里看到的是同一段落内的换行在 GitHub 里却有可能是两行协同办公时很容易引发“排版为什么又变了”的困惑。 表格也是一个重灾区。多数编辑器对表格列数校验不严格少一格照样显示得差不多但一旦进入 GitHub 这类严格按 Markdown 表格规范渲染的平台列数不齐或者分隔行格式错误整张表格都可能变成代码块或者直接消失。图片路径的解析基准也各不相同VSCode 默认相对当前打开文件的位置解析Obsidian 相对仓库根目录解析GitHub 则要求路径必须是仓库内的相对路径三者混用很容易出现“本地能显示、推到远端就裂图”的问题。这些都是同一份测试文档在不同平台跑一遍就能暴露出来的差异。 ## 4. Markdown 高频翻车现场换行、表格、图片路径与特殊字符排查手记 ### 4.1 换行不换行是 Markdown 最容易被误解的设计 “Markdown 换行”这个搜索词排在好几年的热词榜前面说明它坑过的人不计其数。核心要理解的是Markdown 里“单次回车”和“段落结束”是两回事。在原始 Markdown 规范里单次回车会被折叠成一个空格所以你写地址写成三行渲染出来可能挤在一行里。要实现真正的“换行但不断段”传统的做法是在行尾敲两个空格再按回车现代 GFM 则直接允许单次回车就换行。 两种规则各有拥趸实操中的稳妥做法是如果是个人笔记你完全可以依赖现代编辑器的 GFM 行为如果文档要多人协作、跨平台发布我强烈建议遵循“空行分段 行尾两空格软换行”的经典标准。因为两个空格这个写法在任何渲染器中都不会出问题而单次回车则很可能在某个旧环境或严格 CommonMark 渲染器里被折叠掉。遇到列表项里面的自动换行时更要小心前一行末尾如果忘了留空格后一行内容会被当成新列表项而不是对齐文本。 ### 4.2 表格的“能用”与“不好用”对齐方式与转换技巧 表格大概是 Markdown 里最“够用但不好用”的模块。基础写法很简单第一行是表头第二行是分隔行用冒号表示对齐方向:--- 是左对齐:---: 是居中对齐---: 是右对齐。但它的局限同样明显——不支持合并单元格、不支持跨行、单元格里不能放块级元素想在一个格子里面放列表或图片基本是痴人说梦。遇到复杂表格我的经验是直接放弃 Markdown 原生表格改用 HTML 表格标签混排很多渲染器对 HTML table 的支持比想象中好得多。 表格转 Excel 是另一个高频需求。直接整张表格复制到 Excel 里最常见的结果是整个表格被塞进一列需要用 Excel 的“分列”功能处理选中数据点“数据 - 分列”分隔符选择“自定义”并输入竖线 |再清理一下残留的减号行和空格基本上能把数据捞出来。更正规的做法是用 Pandoc 把 Markdown 转成 CSV 再用 Excel 打开或者用 Python 一行 pd.read_markdown(input.md) 读成 DataFrame 再写 Excel适用于有脚本基础的人。无论哪种路线我最想提醒的都是同一个坑转之前检查单元格里有没有遗漏的竖线它是导致分列错乱的头号元凶。 ### 4.3 图片路径为什么我写的图片到了别人电脑上就裂了 图片路径问题在团队协作里出现的频率极高最经典的现象是“在我电脑上明明能显示发给别人就裂了”。根因基本都是路径写死了绝对路径比如在 Windows 上直接写 D:/我的电脑/文档/图片/a.png这串路径在你自己机器上当然有效换一台电脑、上传到 Git 仓库、或者发给 Mac 用户基本必裂。正确做法是使用相对路径让图片相对于当前 Markdown 文件定位。如果文档和图片放在同一个目录下就写 ./images/a.png如果图片在上一级目录就写 ../images/a.png。 相对路径也不是没有坑。第一个坑是平台对路径大小写的敏感度不同GitHub 上的路径是大小写敏感的本地写 ./Images/仓库里文件夹叫 images推送上去就会裂图。第二个坑是路径里尽量不要出现空格和中文尽管多数现代渲染器能处理但在转换工具里经常翻车用 %20 转义或直接改文件名是更省心的做法。第三个坑是 Obsidian 这类知识库工具默认会把附件统一放到一个文件夹它生成的相对路径是针对仓库根目录的解析结果在仓库内用没问题但如果你把单个 .md 文件单独拷给别人路径就会失效。我的建议是给团队规定好一个统一结构每个笔记文件夹下面建一个 images 子目录图片一律放进去文档内统一用以当前文档为基准的相对路径引用。 ### 4.4 方框、带圈序号这类特殊字符怎么输入 热词里出现的“markdown 方框”和“markdown 中圈1到圈19怎么打”说明特殊字符问题困扰着不少人。我先说结论Markdown 本身没有“方块符号”或“带圈数字”的内置语法这些字符本质上就是 Unicode 字符和“你”字“好”字没有区别所以问题就变成了“怎么在文档里输入并确保它正常显示”。 带圈数字的输入方法大概有三种。第一种是用输入法搜狗、微软拼音都可以直接打“圆圈一”找到 ①或者打开系统自带的字符映射表Windows 下输入 charmap从里面选中复制。第二种是用 HTML 实体在 Markdown 里写 #9312; 会显示为 ①#9313; 会显示为 ②一直到 ⑳ 都有对应的码点。第三种是在常用符号面板里选择Mac 用户用 ControlCommand空格 呼出表情与符号面板能找到。方框符号同样可以直接输入空心的 □ 对应 Unicode U25A1带对勾的 ☐ 对应 U2610你可以根据需要直接复制到文档里。 这里最大的坑不是“输入”而是“显示”。部分等宽字体比如老版本的 Consolas、Courier New对带圈数字和方框符号的覆盖并不完整显示出来会变成“豆腐块”或者说一个空方格。如果你发现代码块里的带圈数字显示异常不用怀疑是自己写错了大概率是字体问题把编辑器字体换成微软雅黑、苹方、或者开发者常用的 JetBrains Mono 新版本就能解决。另外在程序代码中如果要用带圈序号直接写 Unicode 转义序列比如 \u2460 会比粘贴原字符更安全不会因为文件编码问题悄悄变成乱码。 ## 5. Markdown 转 Word/Excel 实战从单机转换到自动化工作流 ### 5.1 转换工具选型为什么我首选 Pandoc 把 Markdown 转成 Word 是很多办公场景里的硬需求因为终端用户并不关心你用什么格式写作他们只要一个能交上去的 .docx。最朴素的做法是复制粘贴但 Markdown 的标题、列表、表格结构一旦粘贴到 Word 里十有八九会丢失层级关系修复成本极高。稍微省事一点的办法是利用 Typora 自带的导出能力直接把文件导出为 Word优点是操作简单、样式基本保留缺点是自定义空间小遇到公司模板就无能为力。 如果对转换质量有较高要求我强烈推荐 Pandoc它几乎是目前 Markdown 转 Word 领域最可靠的工具。一条基本的转换命令长这样pandoc input.md -o output.docx。默认转换出来的样式可能比较朴素如果你有公司的 Word 模板可以用 pandoc input.md --reference-doccompany-template.docx -o output.docxPandoc 会以你提供的 docx 模板作为样式参考生成的文档在字体、标题颜色、页边距上都更接近你的要求。这里有个额外提醒reference-doc 模板最好先用 Word 或 Pandoc 生成一个基础版本再在里面修改样式不要直接拿一个包含复杂宏的文档充当模板否则转换容易失败。 ### 5.2 表格转 Excel手动分列、Pandoc 转 CSV、Python 脚本三条路线 如果你只需要把单个 Markdown 表格里的数据喂给 Excel最快的方法还是“复制 分列”我在 4.2 里已经具体讲过分隔符分列的操作了此处不再重复。这个方法适用于表格数量少、格式简单的场景一旦涉及多个文件、多张表格手动的效率就太低了这时候该上脚本和自动化。 Pandoc 路线适合一顿操作猛如虎的环境假设你有个 data.md里面包含若干表格你可以执行 pandoc data.md -t csv -o data.csv然后打开或者用 Excel 进一步处理。不过要提醒的是——Pandoc 转 CSV 会把每个表格都转成一个独立的 CSV 块多个表格时输出文件可能没有想象中干净而且某些复杂表格里的换行符会让 CSV 解析器发疯推荐在转换前先确保目标表格里没有明显的多行单元格。 Python 路线是我个人最常用的尤其当需求变成“定期把 Markdown 里所有表格汇总到一个 Excel 文件”时。代码可以这样起步 python import pandas as pd with open(data.md, encodingutf-8) as f: md_text f.read() tables pd.read_markdown(md_text) # 如果文档里有多个表格read_markdown 返回多个 DataFrame for name, df in tables.items(): df.to_excel(f{name}.xlsx, indexFalse)这里的pd.read_markdown是基于 tabulate 实现的它对 GFM 表格的兼容性不错但文件里如果没有标准的表格分隔行会直接报错。所以脚本开始前先确认数据源的质量是最重要的步骤而不是盲目跑代码。5.3 批量转 Word工作流里的序号自动编号为什么总出问题在实际用工作流平台比如 dify、coze批量转换 Markdown 到 Word 时我最常被问到的问题就是“为什么我用 Markdown 里写的1. 2. 3.转出来的 Word 序号要么消失、要么全部变成数字 1”。这个问题的根因在 Word 的编号机制Word 里的有序列表用的是“列表样式 自动编号”编号数字并不是真实存在于文本里而是由 Word 根据列表顺序自动计算出来的。而 Markdown 转换器在处理有序列表时如果只是把有序列表映射成了 Word 的“正文段落”而没关联到“列表编号”样式那 Word 就没有任何编号可以显示。解决这个事情有几条路。第一种是治标转换完成后手动全选列表文字给它们套上 Word 的“列表编号”样式但遇到几千行的大文档完全不现实。第二种是治本预先准备一个 reference-doc 模板在模板里把“标题 1”“标题 2”“列表编号”等样式系数调好Pandoc 转换时会自动把 Markdown 的有序列表映射成对应的 Word 自动编号列表输出就不用再手动修。第三种是在自动化工作流里多加一个“文档修正”步骤比如在 coze 或 dify 里通过代码节点调用 Python 脚本转换完成后用 python-docx 库扫描并修正编号。这个方案自由度最高适合对输出格式要求严格、需要大批量处理团队文档的场景。5.4 给工作流加“转换前校验”与“转换后比对”自动化批量转换最怕的不是转换失败而是“转换成功但结果悄悄变坏”。我曾经在一个知识库迁移项目里一口气转了三百多个 Markdown 文件到 Word后来同事反馈某个章节的表格列数明显对不上、代码块里的内容被截断问题根因在于原文件里有几行用了不规范的缩进和平行表格Pandoc 转换时没有报错但内容已经悄悄丢了。所以我现在做批量转换时一定会坚持两个额外步骤。转换前跑一段脚本做基础校验检查文档里的括号是否配对、表格列数是否一致、图片路径引用的文件是否存在任何一个检查项不通过就直接把文件名放进报告而不是等到转换结束再逐个核对。转换后再做一次自动比对用脚本提取转换后 Word 文档的标题层级和表格数量和原 Markdown 做一次数量级对比只要数量对不上就可以断定转换过程中有结构损失直接定位到具体文件。这两步看起来不起眼但它们才是批量转换流程里真正值钱的部分。6. 进阶用法把 Markdown 的结构化优势用到 AI 提问里6.1 自然语言 vs MarkdownAI 更吃哪一套最近总在热词里刷到一种争辩对 AI 提问时到底用自然语言还是 Markdown 更容易让 AI 明白指令我自己的大量实测体感是分情况。如果你只是问一个常识问题比如“什么是马尔可夫链”用自然语言就很好Markdown 反而显得用力过猛但如果你的需求包含多个约束条件、多个输出要求或者需要 AI 帮你执行某个多步骤任务Markdown 的结构化表达对 AI 理解意图有显著帮助这一点和人类读文档的体验是相似的——你的提纲越清晰理解你的人越不容易跑偏。为什么因为大模型本质上是一个超强版的“文本接龙器”它对你给出的文本结构的依赖程度比想象中高。用 Markdown 写完任务清单后每个标题、每个加粗、每个列表项都相当于显式告诉模型这里是目标、那里是约束、最后是输出格式。信息边界清楚了模型就不容易把“约束条件”当成“待办事项”来执行。一个直观的验证方法是同样一个需求分别用纯自然语言和 Markdown 写两版并发给同一个模型对比返回结果的有效性你大概率会看到结构化版本在执行类任务上表现更稳。6.2 一个可直接套用的 Markdown 提问模板我自己在写有明确交付要求的 Prompt 时会这样组织结构# 任务目标 把下面的客户反馈记录整理成一份问题清单标注紧急程度。 ## 背景信息 这是一家零售门店最近一周客服收到了以下投诉格式比较乱。 ## 输入内容 - 昨天有个客人说门口排队太久等候 20 分钟没人接待。 - 会员卡充值时系统报错两次充值完成但余额没到账。 - 线上订单发货后两天没有物流信息。 ## 输出要求 1. 每条问题一行按紧急程度从高到低排序。 2. 每条问题后面带上问题可能的根因控制在 30 字内。 3. 最后用表格汇总问题描述 / 紧急程度 / 建议处理部门。 ## 格式要求 输出使用 Markdown开头直接给结果不要分析过程。这里有几个细节值得模仿目标放在最前面让模型第一时间锁定任务方向背景信息单独成段补充上下文但不混杂指令输出要求用有序列表明确列出每条交付细节格式要求直接声明“输出使用 Markdown”减少格式偏移。这套模板并不复杂但比一句“帮我整理一下这些投诉”的输出稳定性高很多。我的建议是不要为了结构化而失去自然语言的温度。最有效的方式是把两者结合背景和语境用自然的语言写清楚任务流程、约束条件、输出格式用 Markdown 的标题和列表列明。这样模型既有足够的上下文可推理又有清晰的任务框架可执行还能兼顾人们在阅读时对“结构化摘要”的自然偏好。6.3 Obsidian 里的折叠块和隐藏内容怎么处理与 AI 提问并行的进阶用法是围绕 Obsidian 这类编辑器的特殊语法需求。比如“obsidian 的 markdown 格式块可以折叠么”也是一个高频问题。Obsidian 本身并没有像 Word 那样可视化的“折叠标题”按钮但它是支持折叠块效果的只不过调用的是 HTML 的details标签。写法非常直接details summary点击展开查看详细内容/summary 这里是要折叠的内容支持 Markdown 语法。 可以包含列表、表格、代码块等元素。 /details在 Obsidian 阅读视图中上面这段会渲染成一个可点击展开的折叠区域点击前只显示 summary 里的文字。需要注意的是这个details标签并不是标准 Markdown 语法所以它只在支持 HTML 标签混排的编辑器里生效。像 GitHub 的 Issue 和 Wiki 同样支持这个标签但一些只做纯文本渲染的工具可能不生效。如果你写的内容要在多个平台间搬运我的建议是折叠块只作为“阅读增强”核心内容不要全都藏进折叠区以免在某个不支持的环境里直接消失。还有一点在details内部如果要继续用 Markdown 语法注意要在开始标签之后留一个空行否则部分渲染器会把后续内容当作 HTML 文本不解析 Markdown。折叠块之外Obsidian 的 Callout 也很值得写进 Markdown 进阶技能清单。写法是 [!note]或者 [!warning]加内容可以快速生成醒目的提示框。不过这个语法主要是 Obsidian 生态内的玩法其他平台基本不支持属于典型“知识库内顺手用、跨平台就打回原形”的类型使用前要判断好场景。这几年用下来我最大的感受是 Markdown 真正难的不是语法本身而是对语法边界和生态差异的把握。最后再分享一个压箱底的小技巧每次拿到一个新编辑器、新平台或者新转换工具我第一件事就是把我前文那份测试文档丢进去跑一遍10 分钟就能摸清这个工具的性格——哪些语法可靠、哪些行为诡异、哪些扩展不稳定全部记录在案。这个习惯帮我避开了大量“文档到同事手里就乱掉”的尴尬也让我在给团队制定写作规范时底气足了很多真的值得你试试。 Markdown语法大全与全面测试文档：从渲染一致性到转换实战
看到“Markdown 语法大全 - 全面测试文档”这个标题时我第一反应是语法大全不稀奇稀奇的是“测试文档”这四个字。作为常年用 Markdown 写技术文档、做知识管理、还经常要把文档转成 Word/Excel 交付给同事的人我太清楚这几个字的分量了。语法谁都会背真正难的是让你的 Markdown 在任何编辑器、任何平台、任何转换链路上渲染出来的结果都符合预期。这篇博文就想围绕“全面测试文档”这个角度把 Markdown 的核心语法、选型逻辑、实操细节和踩坑经验一次讲透适合正在系统学习 Markdown 的初学者也适合想统一团队文档规范、减少“复制过去就乱了”这类麻烦的老手参考。1. 从“语法大全”到“测试文档”Markdown 到底在解决什么问题1.1 Markdown 能火靠的是“语义优先”而不是“页面漂亮”很多人第一次接触 Markdown 都会有个共同疑问它看起来不就是纯文本加几个符号吗为什么能成为程序员、产品经理、自媒体写手都离不开的格式我的理解是Markdown 的核心贡献不是让你“排版更漂亮”而是把文档从“表现层”拉回到了“语义层”。传统 Word 文档里一个一级标题的本质是字体大小 16 磅、加粗、段前段后 12 磅换台电脑字体缺失整个版式就崩了。Markdown 里的#就单纯表达“这里是个一级标题”至于它在屏幕上显示成多大字号、什么颜色完全交给渲染器决定。这就带来一个巨大的好处同一份.md文件在 Typora、Obsidian、VSCode、GitHub 网页上打开骨架永远是一致的变的只是“皮肤”。对于需要长期维护、多人协作、多端同步的文档来说这种稳定性比美貌值钱得多。语法大全类的文章往往只做一件事把符号列出来告诉你它是什么意思。但真正决定 Markdown 使用体验的是对这套“语义优先”逻辑的理解。你知道1.开头是有序列表但你知道列表嵌套在多数渲染器里要求缩进 2 到 4 个空格缩进错了直接解析成普通段落吗你知道表格写完后在 Typora 里显示得好好的复制到 GitHub Issue 里却可能因为列数不齐整体烂掉吗这些都属于“测试文档”要回答的问题而不是“语法大全”能覆盖的。1.2 “全面测试文档”真正该验证的是渲染一致性既然叫“全面测试文档”那它的定位就不是教学材料而是一份“验收清单”。你可以把它理解成软件测试里的冒烟测试每次拿到一个新的 Markdown 编辑器、一个新的渲染平台、或者一条新的转换链路先把这份文档丢进去跑一遍看哪些语法正常工作、哪些行为异常心里就有底了。我建议所有重度 Markdown 用户都维护一份自己的测试文档至少覆盖这样几个维度标题层级是否完整、列表嵌套是否正常、代码块语言高亮是否生效、表格对齐是否保留、行内代码里出现特殊符号是否有问题、图片相对路径能否被正确解析、中文锚点和特殊字符能不能跳转、数学公式和图表扩展是否可用。每验证新环境前花 10 分钟跑一遍比遇到问题时再去查资料高效得多。我自己实际踩过的例子有一版文档在本地 Obsidian 里任务列表渲染非常正常但发给同事用 Typora 打开- [ ]直接变成了普通圆点列表后面还跟了个奇怪的方括号字符串。两个人排查了半天发现是跨平台换行符在作祟。这类问题没有测试文档你是很难提前预判的。2. 手把手搭一份可复用的全要素 Markdown 测试文档2.1 测试文档的内容结构怎么组织我在实际使用中把 Markdown 渲染元素分成三类块级元素、行内元素、扩展元素。块级元素包括标题、段落、列表、引用、代码块、分隔线、表格它们决定文档的整体骨架行内元素包括加粗、斜体、删除线、行内代码、链接、图片它们负责在段落里做局部修饰扩展元素则指那些不在原始 Markdown 规范里、但现代主流编辑器几乎都支持的语法比如任务列表、数学公式、Mermaid 图表、HTML 标签混排。测试文档的设计思路应该按这三个层级展开先验证最基础的块级和行内语法再验证扩展语法。不建议把所有语法平铺在一起写成长篇否则一旦某个地方渲染出错你很难快速定位是哪一类语法的问题。我自己习惯把每个模块单独用分隔线隔开并在每个模块开头用一段注释性质的说明文字标注“本段测试意图”这样无论是人工看还是截图对比都很直观。2.2 一份可以直接套用的测试文档模板先说结论下面是目前我在多个编辑器之间做兼容性测试时用的一个基础模板各位可以直接复制保存成一个markdown-test.md文件。# 一级标题 ## 二级标题 ### 三级标题 普通段落这里包含行内加粗 **加粗**、斜体 *斜体*、删除线 ~~删除线~~以及行内代码 const a 1。 --- - 无序列表项 - 继续 - 嵌套项缩进 2 空格 - 回到外层 1. 有序列表第一项 2. 有序列表第二项 1. 嵌套有序列表 3. 有序列表第三项 - [ ] 未完成任务 - [x] 已完成任务 引用内容 引用段落第二行 javascript function hello() { console.log(hello markdown); }左对齐居中对齐右对齐单元格单元格单元格第二行第二行第二行普通链接行尾两个空格加上回车可以实现软换行HTML 混排测试红色文字这里要特别提醒两点。第一代码块内的符号切勿省略语言标注 javascript 和 的渲染效果在大部分平台上差距很大前者会触发语法高亮后者默认是没有高亮的。第二表格建议标题栏和分隔行之间不要留空行很多渲染器对表格前后的空行解析很敏感你在这里多按一个回车表格可能就断成两截。 ### 2.3 拿到模板后怎么跑一遍“验收流程” 模板只是素材怎么用才是关键。我的习惯是三步走先在目标编辑器里打开这个文件确认显示效果然后按编辑器提供的导出能力分别导出 HTML 和 PDF检查导出版本和预览版本是否一致最后把原文件内容粘贴到目标平台GitHub Issue、团队 Wiki、公众号后台等观察同一个 Markdown 在被别人二次处理时有没有变样。 三步走的过程中我会拿一张 Excel 表格来做记录每行是一个语法模块每列是一个测试环境遇到渲染正常就打“通过”异常就写下异常内容和复现步骤。这个记录一旦积累了十个以上环境的测试结果基本就相当于一份“渲染兼容性地图”。以后同事问我“这个语法在某某平台能不能用”我不用当场猜直接查表就有答案。 ## 3. 编辑器与在线平台实测VSCode、Typora、Obsidian、GitHub 的渲染差异 ### 3.1 主流 Markdown 环境的定位差异 选编辑器之前先想清楚你的使用场景这点比纠结哪个编辑器“最强”重要得多。我用过一段时间把 Typora、Obsidian、VSCode 全部装好想找一个“完美工具”后来发现三个环境各有明确分工根本不存在谁替代谁的问题。下面这个对比是我个人高频使用后的总结 | 工具 | 核心定位 | 最强场景 | 主要局限 | | ---- | ---- | ---- | ---- | | Typora | 所见即所得写作 | 单篇长文、导出精美文档 | 偏重写作知识管理能力弱 | | Obsidian | 本地知识库 | 双链笔记、个人知识管理 | 扩展语法依赖插件 | | VSCode | 代码与文档一体化 | 开发者写技术文档 | 心智能量占用高上手有门槛 | | GitHub | 在线协作与托管 | 开源项目、Issue、Wiki | 离线不可用私人仓库渲染受限 | 说几个我实测下来的细节。Typora 的文件树和导出能力在同类工具里做得很成熟适合作为团队文档的统一编辑端。Obsidian 对本地 Markdown 文件的管理方式几乎是直觉级的它默认会把附件放到一个指定文件夹并自动把文档内的图片路径改成相对路径这点对知识库非常友好但需要注意它内置的很多“增强语法”其实是插件带来的换到其他编辑器里就会失效。VSCode 的优势在于完全开放Markdown 插件生态比另外两者丰富得多只要你愿意花时间调教它能做到几乎完美的写作体验和版本管理结合。 ### 3.2 VSCode写Markdown插件组合与内置预览技巧 如果你主要用 VSCode 写 Markdown我建议至少安装两个插件Markdown All in One 和 Markdown Preview Enhanced。Markdown All in One 解决的是写作效率问题它能一键生成目录、自动编号、格式化表格、为标题自动添加序号还支持快捷键快速插入粗体、斜体、代码块。这些能力看起来基础但累积起来能省下大量时间。Markdown Preview Enhanced 则解决的是预览和导出问题支持自定义 CSS、MathJax 数学公式、代码高亮还能把 Markdown 导出为 HTML、PDF、图片甚至可以直接打开一个浏览器窗口做实时预览。 有一个关于内置预览的点值得单独说一下新版 VSCode 的 Markdown 预览其实已经内置了对数学公式和图表的支持很多教程还在教你怎么装额外插件其实只需要在设置里把 markdown.math 和 markdown.mermaid 相关选项打开就行。这个细节特别容易踩坑——如果你明明安装了插件但图表预览不出来先检查一下是不是被内置设置拦截了。使用预览时我会开启“跟随光标”模式写完一段扫一眼渲染结果比全文写完了再统一预览要稳妥很多有问题能当场发现不用滚动半天找是哪段语法出了问题。 ### 3.3 同一份文档在不同平台渲染结果的差异清单 同一个 Markdown 文件在不同平台的渲染结果真的会不一样这不是哪家做得不好而是 Markdown 的标准本身留下了太多模糊地带。最容易感知到的差异是换行规则标准 CommonMark 语法里单次换行会被当作普通空格处理两次连续换行才会产生新段落但 GitHub 采用 GFM 规范默认把单次换行也渲染成换行。这就意味着同一份文档里如果你只按了一次回车在 Typora 里看到的是同一段落内的换行在 GitHub 里却有可能是两行协同办公时很容易引发“排版为什么又变了”的困惑。 表格也是一个重灾区。多数编辑器对表格列数校验不严格少一格照样显示得差不多但一旦进入 GitHub 这类严格按 Markdown 表格规范渲染的平台列数不齐或者分隔行格式错误整张表格都可能变成代码块或者直接消失。图片路径的解析基准也各不相同VSCode 默认相对当前打开文件的位置解析Obsidian 相对仓库根目录解析GitHub 则要求路径必须是仓库内的相对路径三者混用很容易出现“本地能显示、推到远端就裂图”的问题。这些都是同一份测试文档在不同平台跑一遍就能暴露出来的差异。 ## 4. Markdown 高频翻车现场换行、表格、图片路径与特殊字符排查手记 ### 4.1 换行不换行是 Markdown 最容易被误解的设计 “Markdown 换行”这个搜索词排在好几年的热词榜前面说明它坑过的人不计其数。核心要理解的是Markdown 里“单次回车”和“段落结束”是两回事。在原始 Markdown 规范里单次回车会被折叠成一个空格所以你写地址写成三行渲染出来可能挤在一行里。要实现真正的“换行但不断段”传统的做法是在行尾敲两个空格再按回车现代 GFM 则直接允许单次回车就换行。 两种规则各有拥趸实操中的稳妥做法是如果是个人笔记你完全可以依赖现代编辑器的 GFM 行为如果文档要多人协作、跨平台发布我强烈建议遵循“空行分段 行尾两空格软换行”的经典标准。因为两个空格这个写法在任何渲染器中都不会出问题而单次回车则很可能在某个旧环境或严格 CommonMark 渲染器里被折叠掉。遇到列表项里面的自动换行时更要小心前一行末尾如果忘了留空格后一行内容会被当成新列表项而不是对齐文本。 ### 4.2 表格的“能用”与“不好用”对齐方式与转换技巧 表格大概是 Markdown 里最“够用但不好用”的模块。基础写法很简单第一行是表头第二行是分隔行用冒号表示对齐方向:--- 是左对齐:---: 是居中对齐---: 是右对齐。但它的局限同样明显——不支持合并单元格、不支持跨行、单元格里不能放块级元素想在一个格子里面放列表或图片基本是痴人说梦。遇到复杂表格我的经验是直接放弃 Markdown 原生表格改用 HTML 表格标签混排很多渲染器对 HTML table 的支持比想象中好得多。 表格转 Excel 是另一个高频需求。直接整张表格复制到 Excel 里最常见的结果是整个表格被塞进一列需要用 Excel 的“分列”功能处理选中数据点“数据 - 分列”分隔符选择“自定义”并输入竖线 |再清理一下残留的减号行和空格基本上能把数据捞出来。更正规的做法是用 Pandoc 把 Markdown 转成 CSV 再用 Excel 打开或者用 Python 一行 pd.read_markdown(input.md) 读成 DataFrame 再写 Excel适用于有脚本基础的人。无论哪种路线我最想提醒的都是同一个坑转之前检查单元格里有没有遗漏的竖线它是导致分列错乱的头号元凶。 ### 4.3 图片路径为什么我写的图片到了别人电脑上就裂了 图片路径问题在团队协作里出现的频率极高最经典的现象是“在我电脑上明明能显示发给别人就裂了”。根因基本都是路径写死了绝对路径比如在 Windows 上直接写 D:/我的电脑/文档/图片/a.png这串路径在你自己机器上当然有效换一台电脑、上传到 Git 仓库、或者发给 Mac 用户基本必裂。正确做法是使用相对路径让图片相对于当前 Markdown 文件定位。如果文档和图片放在同一个目录下就写 ./images/a.png如果图片在上一级目录就写 ../images/a.png。 相对路径也不是没有坑。第一个坑是平台对路径大小写的敏感度不同GitHub 上的路径是大小写敏感的本地写 ./Images/仓库里文件夹叫 images推送上去就会裂图。第二个坑是路径里尽量不要出现空格和中文尽管多数现代渲染器能处理但在转换工具里经常翻车用 %20 转义或直接改文件名是更省心的做法。第三个坑是 Obsidian 这类知识库工具默认会把附件统一放到一个文件夹它生成的相对路径是针对仓库根目录的解析结果在仓库内用没问题但如果你把单个 .md 文件单独拷给别人路径就会失效。我的建议是给团队规定好一个统一结构每个笔记文件夹下面建一个 images 子目录图片一律放进去文档内统一用以当前文档为基准的相对路径引用。 ### 4.4 方框、带圈序号这类特殊字符怎么输入 热词里出现的“markdown 方框”和“markdown 中圈1到圈19怎么打”说明特殊字符问题困扰着不少人。我先说结论Markdown 本身没有“方块符号”或“带圈数字”的内置语法这些字符本质上就是 Unicode 字符和“你”字“好”字没有区别所以问题就变成了“怎么在文档里输入并确保它正常显示”。 带圈数字的输入方法大概有三种。第一种是用输入法搜狗、微软拼音都可以直接打“圆圈一”找到 ①或者打开系统自带的字符映射表Windows 下输入 charmap从里面选中复制。第二种是用 HTML 实体在 Markdown 里写 #9312; 会显示为 ①#9313; 会显示为 ②一直到 ⑳ 都有对应的码点。第三种是在常用符号面板里选择Mac 用户用 ControlCommand空格 呼出表情与符号面板能找到。方框符号同样可以直接输入空心的 □ 对应 Unicode U25A1带对勾的 ☐ 对应 U2610你可以根据需要直接复制到文档里。 这里最大的坑不是“输入”而是“显示”。部分等宽字体比如老版本的 Consolas、Courier New对带圈数字和方框符号的覆盖并不完整显示出来会变成“豆腐块”或者说一个空方格。如果你发现代码块里的带圈数字显示异常不用怀疑是自己写错了大概率是字体问题把编辑器字体换成微软雅黑、苹方、或者开发者常用的 JetBrains Mono 新版本就能解决。另外在程序代码中如果要用带圈序号直接写 Unicode 转义序列比如 \u2460 会比粘贴原字符更安全不会因为文件编码问题悄悄变成乱码。 ## 5. Markdown 转 Word/Excel 实战从单机转换到自动化工作流 ### 5.1 转换工具选型为什么我首选 Pandoc 把 Markdown 转成 Word 是很多办公场景里的硬需求因为终端用户并不关心你用什么格式写作他们只要一个能交上去的 .docx。最朴素的做法是复制粘贴但 Markdown 的标题、列表、表格结构一旦粘贴到 Word 里十有八九会丢失层级关系修复成本极高。稍微省事一点的办法是利用 Typora 自带的导出能力直接把文件导出为 Word优点是操作简单、样式基本保留缺点是自定义空间小遇到公司模板就无能为力。 如果对转换质量有较高要求我强烈推荐 Pandoc它几乎是目前 Markdown 转 Word 领域最可靠的工具。一条基本的转换命令长这样pandoc input.md -o output.docx。默认转换出来的样式可能比较朴素如果你有公司的 Word 模板可以用 pandoc input.md --reference-doccompany-template.docx -o output.docxPandoc 会以你提供的 docx 模板作为样式参考生成的文档在字体、标题颜色、页边距上都更接近你的要求。这里有个额外提醒reference-doc 模板最好先用 Word 或 Pandoc 生成一个基础版本再在里面修改样式不要直接拿一个包含复杂宏的文档充当模板否则转换容易失败。 ### 5.2 表格转 Excel手动分列、Pandoc 转 CSV、Python 脚本三条路线 如果你只需要把单个 Markdown 表格里的数据喂给 Excel最快的方法还是“复制 分列”我在 4.2 里已经具体讲过分隔符分列的操作了此处不再重复。这个方法适用于表格数量少、格式简单的场景一旦涉及多个文件、多张表格手动的效率就太低了这时候该上脚本和自动化。 Pandoc 路线适合一顿操作猛如虎的环境假设你有个 data.md里面包含若干表格你可以执行 pandoc data.md -t csv -o data.csv然后打开或者用 Excel 进一步处理。不过要提醒的是——Pandoc 转 CSV 会把每个表格都转成一个独立的 CSV 块多个表格时输出文件可能没有想象中干净而且某些复杂表格里的换行符会让 CSV 解析器发疯推荐在转换前先确保目标表格里没有明显的多行单元格。 Python 路线是我个人最常用的尤其当需求变成“定期把 Markdown 里所有表格汇总到一个 Excel 文件”时。代码可以这样起步 python import pandas as pd with open(data.md, encodingutf-8) as f: md_text f.read() tables pd.read_markdown(md_text) # 如果文档里有多个表格read_markdown 返回多个 DataFrame for name, df in tables.items(): df.to_excel(f{name}.xlsx, indexFalse)这里的pd.read_markdown是基于 tabulate 实现的它对 GFM 表格的兼容性不错但文件里如果没有标准的表格分隔行会直接报错。所以脚本开始前先确认数据源的质量是最重要的步骤而不是盲目跑代码。5.3 批量转 Word工作流里的序号自动编号为什么总出问题在实际用工作流平台比如 dify、coze批量转换 Markdown 到 Word 时我最常被问到的问题就是“为什么我用 Markdown 里写的1. 2. 3.转出来的 Word 序号要么消失、要么全部变成数字 1”。这个问题的根因在 Word 的编号机制Word 里的有序列表用的是“列表样式 自动编号”编号数字并不是真实存在于文本里而是由 Word 根据列表顺序自动计算出来的。而 Markdown 转换器在处理有序列表时如果只是把有序列表映射成了 Word 的“正文段落”而没关联到“列表编号”样式那 Word 就没有任何编号可以显示。解决这个事情有几条路。第一种是治标转换完成后手动全选列表文字给它们套上 Word 的“列表编号”样式但遇到几千行的大文档完全不现实。第二种是治本预先准备一个 reference-doc 模板在模板里把“标题 1”“标题 2”“列表编号”等样式系数调好Pandoc 转换时会自动把 Markdown 的有序列表映射成对应的 Word 自动编号列表输出就不用再手动修。第三种是在自动化工作流里多加一个“文档修正”步骤比如在 coze 或 dify 里通过代码节点调用 Python 脚本转换完成后用 python-docx 库扫描并修正编号。这个方案自由度最高适合对输出格式要求严格、需要大批量处理团队文档的场景。5.4 给工作流加“转换前校验”与“转换后比对”自动化批量转换最怕的不是转换失败而是“转换成功但结果悄悄变坏”。我曾经在一个知识库迁移项目里一口气转了三百多个 Markdown 文件到 Word后来同事反馈某个章节的表格列数明显对不上、代码块里的内容被截断问题根因在于原文件里有几行用了不规范的缩进和平行表格Pandoc 转换时没有报错但内容已经悄悄丢了。所以我现在做批量转换时一定会坚持两个额外步骤。转换前跑一段脚本做基础校验检查文档里的括号是否配对、表格列数是否一致、图片路径引用的文件是否存在任何一个检查项不通过就直接把文件名放进报告而不是等到转换结束再逐个核对。转换后再做一次自动比对用脚本提取转换后 Word 文档的标题层级和表格数量和原 Markdown 做一次数量级对比只要数量对不上就可以断定转换过程中有结构损失直接定位到具体文件。这两步看起来不起眼但它们才是批量转换流程里真正值钱的部分。6. 进阶用法把 Markdown 的结构化优势用到 AI 提问里6.1 自然语言 vs MarkdownAI 更吃哪一套最近总在热词里刷到一种争辩对 AI 提问时到底用自然语言还是 Markdown 更容易让 AI 明白指令我自己的大量实测体感是分情况。如果你只是问一个常识问题比如“什么是马尔可夫链”用自然语言就很好Markdown 反而显得用力过猛但如果你的需求包含多个约束条件、多个输出要求或者需要 AI 帮你执行某个多步骤任务Markdown 的结构化表达对 AI 理解意图有显著帮助这一点和人类读文档的体验是相似的——你的提纲越清晰理解你的人越不容易跑偏。为什么因为大模型本质上是一个超强版的“文本接龙器”它对你给出的文本结构的依赖程度比想象中高。用 Markdown 写完任务清单后每个标题、每个加粗、每个列表项都相当于显式告诉模型这里是目标、那里是约束、最后是输出格式。信息边界清楚了模型就不容易把“约束条件”当成“待办事项”来执行。一个直观的验证方法是同样一个需求分别用纯自然语言和 Markdown 写两版并发给同一个模型对比返回结果的有效性你大概率会看到结构化版本在执行类任务上表现更稳。6.2 一个可直接套用的 Markdown 提问模板我自己在写有明确交付要求的 Prompt 时会这样组织结构# 任务目标 把下面的客户反馈记录整理成一份问题清单标注紧急程度。 ## 背景信息 这是一家零售门店最近一周客服收到了以下投诉格式比较乱。 ## 输入内容 - 昨天有个客人说门口排队太久等候 20 分钟没人接待。 - 会员卡充值时系统报错两次充值完成但余额没到账。 - 线上订单发货后两天没有物流信息。 ## 输出要求 1. 每条问题一行按紧急程度从高到低排序。 2. 每条问题后面带上问题可能的根因控制在 30 字内。 3. 最后用表格汇总问题描述 / 紧急程度 / 建议处理部门。 ## 格式要求 输出使用 Markdown开头直接给结果不要分析过程。这里有几个细节值得模仿目标放在最前面让模型第一时间锁定任务方向背景信息单独成段补充上下文但不混杂指令输出要求用有序列表明确列出每条交付细节格式要求直接声明“输出使用 Markdown”减少格式偏移。这套模板并不复杂但比一句“帮我整理一下这些投诉”的输出稳定性高很多。我的建议是不要为了结构化而失去自然语言的温度。最有效的方式是把两者结合背景和语境用自然的语言写清楚任务流程、约束条件、输出格式用 Markdown 的标题和列表列明。这样模型既有足够的上下文可推理又有清晰的任务框架可执行还能兼顾人们在阅读时对“结构化摘要”的自然偏好。6.3 Obsidian 里的折叠块和隐藏内容怎么处理与 AI 提问并行的进阶用法是围绕 Obsidian 这类编辑器的特殊语法需求。比如“obsidian 的 markdown 格式块可以折叠么”也是一个高频问题。Obsidian 本身并没有像 Word 那样可视化的“折叠标题”按钮但它是支持折叠块效果的只不过调用的是 HTML 的details标签。写法非常直接details summary点击展开查看详细内容/summary 这里是要折叠的内容支持 Markdown 语法。 可以包含列表、表格、代码块等元素。 /details在 Obsidian 阅读视图中上面这段会渲染成一个可点击展开的折叠区域点击前只显示 summary 里的文字。需要注意的是这个details标签并不是标准 Markdown 语法所以它只在支持 HTML 标签混排的编辑器里生效。像 GitHub 的 Issue 和 Wiki 同样支持这个标签但一些只做纯文本渲染的工具可能不生效。如果你写的内容要在多个平台间搬运我的建议是折叠块只作为“阅读增强”核心内容不要全都藏进折叠区以免在某个不支持的环境里直接消失。还有一点在details内部如果要继续用 Markdown 语法注意要在开始标签之后留一个空行否则部分渲染器会把后续内容当作 HTML 文本不解析 Markdown。折叠块之外Obsidian 的 Callout 也很值得写进 Markdown 进阶技能清单。写法是 [!note]或者 [!warning]加内容可以快速生成醒目的提示框。不过这个语法主要是 Obsidian 生态内的玩法其他平台基本不支持属于典型“知识库内顺手用、跨平台就打回原形”的类型使用前要判断好场景。这几年用下来我最大的感受是 Markdown 真正难的不是语法本身而是对语法边界和生态差异的把握。最后再分享一个压箱底的小技巧每次拿到一个新编辑器、新平台或者新转换工具我第一件事就是把我前文那份测试文档丢进去跑一遍10 分钟就能摸清这个工具的性格——哪些语法可靠、哪些行为诡异、哪些扩展不稳定全部记录在案。这个习惯帮我避开了大量“文档到同事手里就乱掉”的尴尬也让我在给团队制定写作规范时底气足了很多真的值得你试试。