这次话题有点“老生常谈”，但正因为它老，我反而想把Markdown从头到尾彻底捋一遍。起因很简单：前阵子帮同事整理一套交付文档，发现连“换行”这种最基础的细节都能争论半天——有人按一次回车以为就是换行，有人把表格从GitHub复制到Excel结果挤成一团，还有人想在笔记里写个数学公式，却不知道去哪装插件。这些碎片化的问题，恰好凑成了Markdown学习的完整拼图。所以我决定把这份经验整理成文：从语法细节讲到数学公式插件、编辑器和阅读器，再到表格转Excel、转Word、转流程图，以及现在很火的AI网页存档工作流。适合正在入门Markdown的文档新手，也适合想补齐工具链的开发者、自媒体和知识库爱好者。

1. 起点：重拾Markdown，先认清它解决的真实问题

1.1 为什么Markdown值得系统学一遍

很多人把Markdown当成“一种轻量语法”，这个理解没错，但远远不够。Markdown真正的价值在于：它把内容的表达和内容的呈现彻底分离了。你用纯文本写的标题、列表、引用、表格，在任何支持Markdown的平台上都能被解释成格式统一的文档；而不像Word里那样，格式附着在光标位置，换个软件排版就乱。

我见过太多人问“Markdown文件怎么打开”，其实答案很简单：.md文件本质是纯文本，Windows里的记事本、macOS里的文本编辑、Linux里的任何一个终端编辑器都能打开。但“能打开”不等于“能看爽”，所以后面我花了整整一章讲编辑器与阅读器选型。这套选型逻辑，比语法本身更能决定你用得舒不舒服。

Markdown值得系统学，主要因为它解决的三个痛点很少被其他工具同时覆盖：

• 写作时不被打断：不用盯着工具栏找字号颜色，鼠标不需要频繁脱离键盘。
• 纯文本可管理：可以进Git做版本管理，可以被grep搜索，几十年的项目文档都能回溯变更历史。
• 一处编写、多处渲染：同一个文件可以发布成博客、转成PPT、被AI工具读取，也可以生成PDF或Word。

我常说一句话：Markdown是写作的“源代码”，Word是“编译后的产物”。如果你写过代码，很容易理解为什么维护源码比直接改产物更靠谱。没写过代码也没关系，你只要记住：所有用Markdown写的文档，未来都可以被批量转化成其他格式，而普通编辑器做不到。

1.2 基础语法的“记号表”：少背符号，多理解场景

网上到处都是Markdown语法速查表，背完就忘，因为它是零散的符号记忆。我更推荐按“写作场景”来理解语法：你现在要表达什么，就用对应的记号去标记它。

这套“记号表”我建议你这么用：先别管每个符号的所有变体，每次写作时只问自己“我现在要表达哪类意图”，然后去查对应记号。写两三次，自然就记住了。真正让你写不顺的不是语法本身，而是“脑子里想表达层级关系，手上却不知道该用标题还是列表”。这个判断力，只有多写才能形成。

1.3 一段示例串起常用语法

我用一段实际文档把常用语法串起来，你复制到任何Markdown编辑器里都能看到效果：

# 项目周报 > 本周核心目标：完成API模块联调并输出验收文档。 ## 1. 完成事项 - 完成登录接口的参数校验逻辑 - 修复历史数据导出内存溢出问题 - 整理数据库字段字典 ## 2. 下周计划 1. 联调支付回调链路 2. 编写压测脚本 3. 评审前端组件库选型 ## 3. 关键数据 | 模块 | 进度 | 负责人 | | --- | --- | --- | | 网关 | 90% | 阿明 | | 订单 | 75% | 小雨 | ## 4. 技术要点 通过 `JWT` 做状态校验，避免 `session` 在多实例下的同步问题。 ```javascript const token = jwt.sign({ userId }, secret, { expiresIn: '7d' });

编译前注意环境变量NODE_ENV是否为production，这里容易踩坑。

这一小段里，标题层级、引用、无序列表、有序列表、表格、行内代码、代码块、加粗全部出现。你写完这段再去对比语法表，会发现记忆成本低得多。 ## 2. 最容易被折腾的几个细节：换行、代码块、图片路径 ### 2.1 换行：为什么按回车却没换行 问“Markdown换行”的人，十有八九遇到过这个诡异现象：在编辑器里明明按了回车，渲染出来却是连在一起的同一段话。这不是软件Bug，而是Markdown的设计规则：在Markdown里，**普通回车只代表“软换行”，不一定生成一个新段落**。 具体规则是这样的： | 你做的操作 | 渲染结果 | 适用场景 | | --- | --- | --- | | 行尾不空格，直接回车 | 多数平台会合并成同一段落 | 普通连续文本 | | 行尾加两个空格再回车 | 明确换行，但仍算同一段落 | 诗歌、地址 | | 两次回车（中间空一行） | 生成新段落，段间有间距 | 文章正文分节 | 为什么这么设计？因为Markdown最初是为HTML写作服务的，而HTML里换行本身就不直接对应段落。在HTML中，普通的换行会被视作空格，只有`<br/>`才是硬换行。Markdown继承了这个逻辑，行尾两个空格对应的就是`<br/>`。 我的实操建议：别纠结两个空格，遇到需要换行的地方，直接空一行分段。因为两个空格在部分平台（比如某些博客后端）渲染不稳定，复制到别处可能失效；而空行分段是所有平台都认的。 ### 2.2 插入code：行内代码和代码块的取舍 “Markdown插入code”也是个高频问题。代码相关的语法分两层，用错会直接影响阅读体验。 第一层是行内代码，用单个反引号包裹： ```markdown 执行命令前请先设置 `JAVA_HOME` 环境变量。

第二层是代码块，用三个反引号包裹，并在后面标注语言：

```python def greet(name): print(f"Hello, {name}")

这里有几个实际坑，我逐个说： - **代码块里想嵌套代码块**：如果展示内容里本身有三个反引号，你可以用四个反引号作为外层包裹，四个以内任意多的反引号都行。很多人的代码高亮异常，就是反引号数量对不上。 - **语言标识不要乱写**：围栏代码块后面加的语言名会被渲染器用于语法高亮，比如`javascript`、`bash`、`json`、`python`。写错不会报错，但高亮会失效。 - **行内代码里的特殊符号不需要转义**：它本来就是给“字面量”用的，里面出现星号、下划线、方括号，都不影响显示。 一个原则：代码块一定要配语言标识，这不仅是高亮问题，也是后续工具链（比如转PDF、转Word）识别代码语义的依据。 ### 2.3 图片路径：相对路径、绝对路径、在线图床 图片是Markdown里最容易被忽视的大坑。你在本地显示的图，换个电脑或发给别人就裂了。先看三种写法的本质差异： ```markdown ![本地相对路径](./assets/images/architecture.png) ![本地绝对路径](/Users/me/project/assets/images/architecture.png) ![在线图床](https://cdn.example.com/images/architecture.png)

我的建议如下：

首选相对路径。把图片放在当前文档所在目录的子文件夹里，比如文档在docs/readme.md，图片放在docs/assets/，就写./assets/xxx.png。这样整个文件夹复制到别处、推到Git仓库，图片都不会丢。这是我用了很久最稳的方案。

避免写死绝对路径。C:/Users/...或/Users/me/...这种路径换个环境就失效，而且如果文档要公开，还会暴露你的电脑目录结构。

多个平台或外部协作时，用图床或在线存储。写公众号、技术社区文章时，把图片传到对象存储或者图床，Markdown里只放URL，渲染速度取决于网络，稳定性也取决于图床服务。

这里给一个最容易踩的坑：图片文件名含有空格或中文时，GitHub等平台解析相对路径可能出问题。最好的习惯是图片文件名统一用小写字母、数字、连字符，比如architecture-overview.png，别用架构 图.png。

3. 工具链：从下载编辑器到Linux阅读器的一次选型

3.1 编辑器怎么下载和选：一句话讲清四大金刚

说到“markdown下载”和“markdown编辑器”，市面上一抓一大把，但适合长期写作的就那么几类。我给你按使用场景排个序：

下载时给你一个硬性建议：只去官网。很多第三方下载站塞了多余插件或广告，这点不能含糊。Typora现在是付费软件，但真的是那种“一用就回不去”的编辑器；如果你不想付费，Obsidian免费开源是首选。VS Code虽然安装包不小，但如果你本来就要写代码，那它就是你最顺手的Markdown编辑器，不用另装任何东西。

3.2 Sublime Text 查看Markdown：给你的轻量编辑器装上预览插件

Sublime Text 是老牌轻量编辑器，常被拿来当作“快速打开单个md文件”的工具。但默认情况下它只能当文本编辑器用，想看渲染效果需要装两个插件，都在Package Control里装：

• MarkdownEditing：提供Markdown语法高亮、自动缩进、护眼配色。
• MarkdownPreview：提供快捷键渲染预览，还能导出HTML。

安装完以后，用快捷键Ctrl + Shift + P（macOS是Cmd + Shift + P）打开命令面板，输入Markdown Preview，选择预览方式，默认浏览器里就能看到渲染后的效果。如果你想让预览走内置浏览器而不弹出外部窗口，MarkdownPreview也提供了侧边预览模式。

Sublime这套组合的优势在于：启动快、占用低，双击一个.md文件就能开写。缺点也明显：没有目录树、没有文档间链接跳转，不适合做大型知识库。把它定位成“随手查看和修改单篇Markdown的文本工具”最合适。

3.3 Linux 下的阅读器选择

Linux 用户读Markdown的场景很常见，毕竟大量开发文档和README都是.md格式。这里分享几套我实测过的方案：

• 终端阅读：装一个mdless，在Shell里直接以翻页形式阅读Markdown，适合服务器上临时看文档，依赖少、响应快。
• GitHub风格渲染：用grip，它会在本地起一个HTTP服务，使用GitHub风格渲染你的Markdown文档。浏览器打开localhost:6419即可。这对写README、调试GitHub显示效果特别有用。
• 完整桌面体验：Obsidian的Linux版直接用AppImage分发，下载后加执行权限就能跑，和Windows端体验基本一致。
• 最小依赖方案：如果你的系统里已经有VS Code，那就真不用再折腾别的阅读器了，内置Markdown预览已经够用。

Linux上我最终的常态组合是：快速阅读用mdless，写文档用VS Code，涉及README格式调试用grip。这三个工具覆盖了九成Markdown场景。

3.4 浏览器扩展兜底：只要是文本都能读

有时候你只是临时拿到一个.md文件，不想安装任何软件，那用浏览器扩展最省事。Chrome、Edge、以及基于Chromium内核的浏览器，甚至360浏览器这类国产浏览器，都在扩展商店里搜“markdown”就能找到一批渲染插件。

这类插件通常的效果是：把本地Markdown文件拖进浏览器窗口，或者从命令行用浏览器打开本地文件，插件会自动把纯文本渲染成带格式的页面，还附带阅读器皮肤。像soar360这类带阅读器风格渲染的扩展，就是典型代表：它的好处是零配置，打开即读；坏处是碰到复杂表格或代码高亮需求时，效果不如桌面编辑器精细。

所以浏览器扩展更合适的定位是“兜底查看器”，而不是“编辑器”。真到了要创作内容的时候，还是回到Typora或VS Code这类正经编辑器里更顺手。

4. 数学公式插件：给Markdown加上TeX能力

4.1 写作中需要数学公式的场景

笔记、博客、技术文档里一旦出现数学公式，Markdown的短板就暴露出来了：它本身不定义数学渲染，必须依赖第三方引擎。最常见的两个引擎是MathJax和KaTeX。简单说，MathJax功能全、老牌稳定，KaTeX渲染快、体积小。现在主流编辑器多数用的是KaTeX，因为实时渲染更快。

公式通常有两种书写形态：

行内公式：勾股定理是 $a^2 + b^2 = c^2$ 这样表达的。 块级公式（独占一行）： $$ \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} $$

如果你在Markdown编辑器里写了这些，但预览页面显示的是原始$符号，说明编辑器里的数学渲染开关没开，或者渲染引擎不支持。

4.2 在编辑器里打开数学公式开关

不同编辑器的入口差异挺大，我逐个说明：

Typora：在“偏好设置”的“Markdown”标签页里，勾选“行内公式”选项。Typora默认支持块级公式，但行内公式有时需要手动开启。开启后，直接输入$...$即可实时渲染。

VS Code：如果你用的是Markdown Preview Enhanced插件，默认就支持墨镜公式语法；如果只用官方内置的Markdown预览，需要安装一个支持KaTeX的插件，这类插件通常以“markdown+math”命名。

Obsidian：默认支持块级公式，但行内公式需要在设置里的“编辑器”选项里把“行内公式”打开。Obsidian的数学渲染走的是MathJax，兼容性不错。

还有一块容易被忽略：在线平台。比如GitHub，本身也支持部分数学公式，但不是所有平台都支持。你在自己的小站或私有部署的文档系统里支持，需要在模板头部加载插件资源。此时安装资源有两种方式：

• 在HTML文档的<head>里引入KaTeX的CSS和JS文件；
• 借助katex.render()方法，在页面加载后用脚本处理页面里所有公式。

常见做法是前者：引入CSS和JS后，再初始化一个自动渲染方法。这个配置方式在不同Markdown渲染系统里大同小异。

4.3 自己搭个预览页面时怎么注入插件

如果你自己写了一个极简Markdown预览页面，想在网页里渲染数学公式，一个最小的HTML骨架大概长这样：

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <title>Markdown 公式预览</title> <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex/dist/katex.min.css"> <script src="https://cdn.jsdelivr.net/npm/markdown-it/dist/markdown-it.min.js"></script> </head> <body> <div id="app"></div> <script> const md = window.markdownit(); md.use(require('@mdit/plugin-katex')); // 按构建方式而定 document.getElementById('app').innerHTML = md.render('# Hello KaTeX\n\n$a^2 + b^2 = c^2$'); </script> </body> </html>

这里的关键点在于：Markdown解析器和数学公式渲染器是两套体系，必须让它们协作。Markdown解析器负责把$...$找出来，KaTeX负责把这一段TeX代码渲染成带样式的HTML。如果你只引入KaTeX却不告诉Markdown解析器“遇到$要按公式处理”，公式就会原样露出来。

4.4 公式不会渲染时的排查思路

我写技术文档时遇到过几次“公式死活不出来”的情况，排查思路差不多是固定的：

1. 确认编辑器或渲染器是否开启数学支持 2. 确认公式里的反斜杠是否被Markdown解析器转义掉了 3. 确认楼主是否在代码块里写了公式（代码块不会渲染数学） 4. 确认网上CDN资源是否被拦截，以及网络是否正常

第二条很容易被人忽略：Markdown里反斜杠是转义符，如果公式里有\frac这类LaTeX命令，有时需要写成双反斜杠，取决于解析器实现。遇到公式显示成纯文本时，先不要怀疑公式写错，先把反斜杠层数调一遍。

5. GitHub专属语法与跨平台兼容：callout只是冰山一角

5.1 GitHub callout 的写法

“GitHub markdown callout”是今年被问得不少的一个点。GitHub在2023年前后正式支持了一种叫“callout”的提示框语法，也叫admonition。写法上类似引用块，但带type标识：

> [!NOTE] > 这是普通提示。 > [!TIP] > 这是建议。 > [!IMPORTANT] > 这是重要信息。 > [!WARNING] > 这是警告。 > [!CAUTION] > 这是小心提醒。

渲染出来以后，GitHub会在引用块前面加一个带色块和图标的提示条，视觉上非常醒目。这个语法在GitHub网页、GitHub Mobile、以及多数GitHub桌面客户端里都是支持的。

问题来了：你现在用Typora本地写文档、用Obsidian管理笔记，或者把一个包含了callout的md文件丢到其它平台，它们未必支持这套语法。在支持它的软件里，渲染结果是五颜六色的提示框；在不支持的渲染器里，只会显示成一堆原始字符[!NOTE]，非常丑。

所以我的建议很明确：重要内容不要用callout来表达。你可以用callout做锦上添花的提示，但核心信息要写在普通段落或普通引用里，保证跨平台不丢内容。

5.2 哪些语法只在GitHub上生效

GitHub对Markdown的方言叫GFM（GitHub Flavored Markdown）。很多你以为“Markdown就该支持”的语法，其实只在GFM里有效。我列一个兼容性速查表：

这里想强调的是：Markdown不是一份标准，它是一族方言。更准确地说，CommonMark是一个共同子集，GFM、Typora、Obsidian各自都扩展了自己的语法。所以当你决定某篇文档要发布到多个平台时，尽量只使用“最大公约数”语法，比如标题、列表、段落、引用、链接、图片、代码块、表格，这些语法各平台都认。

5.3 写Markdown时的“最低兼容公约”

基于上面的差异，我给自己定了一条规则：多平台发布的文章，只用最低兼容公约。具体就是：

• 普通文本和列表承担核心内容，不使用callout承载关键信息；
• 表格不放太多内容，列数控制在5列以内，避免在窄屏上溢出；
• 链接统一用相对路径或完整URL，不用无协议的www.xxx.com；
• 图片路径按相对路径组织，尽量用英文小写文件名；
• 代码块必须标注语言，不标注的话，多数平台不会给高亮；
• 需要强调的内容用加粗而不是下划线（下划线在Markdown中是斜体的另一种写法，可能造成误解）。

这条公约条条都是从踩坑里总结出来的。你只要遵循它，同一份md文件从GitHub复制到语雀、从语雀导出到Word，都不会出现灾难性的排版崩坏。

6. 让Markdown真正“流”起来：转Excel、Word、流程图与AI工作流

6.1 表格复制到Excel：从粘贴到结构化转换

“Markdown表格转换Excel”是办公室日常里最频繁的需求。为什么直接复制粘贴常常失败？因为Excel期望的表格数据是“Tab分隔”或“逗号分隔”的结构化文本，而Markdown表格里包含|分隔符和---对齐行。直接粘贴时Excel会把这些当作普通文本，塞进一列而不是多列。

正确的做法是分两步：

1. 先把Markdown表格里的分隔符去掉，换成Tab分隔符。
2. 再粘贴到Excel里。

手工操作也不复杂：复制整段表格，粘贴到记事本里，把管道符|替换为Tab键（在记事本里直接按Tab），然后全选复制，粘贴到Excel里。第一批数据就会自动分列。

如果你经常要转，推荐用工具一步到位。最简单的是pandoc，如下命令：

pandoc input.md -t csv -o output.csv

这条命令会把Markdown文档里所有表格提取出来，转成CSV。Excel能直接打开CSV文件。如果只想转某个表格，先用文本编辑器把那段表格单独存成一个md文件再跑pandoc。对于不熟悉命令行的同事，我还用过在线转换工具，效果可以，但注意不要把敏感数据贴到不明网站上。

6.2 转Word的两条路线：pandoc命令行与coze工作流

“Markdown转Word”主要有两条路，取决于你的操作习惯。

路线一：本地命令行，pandoc一把梭。

pandoc是文档转换领域的瑞士军刀，支持标记语言互转。把md转成Word最简命令：

pandoc 笔记.md -o 笔记.docx

如果要加标题样式，用--standalone配合模板；如果要让标题自动生成目录，再添加--toc参数：

pandoc 笔记.md -o 笔记.docx --toc --standalone

Pandoc转换出来的Word文档默认样式朴素，但胜在结构完整。你可以在Word里直接改默认样式，或者准备一个dotx模板，通过--reference-doc指定。我建议第一次转换后，把调好的dotx模板存下来，以后每次转换都用它，能省下大量调格式的时间。

路线二：无代码自动化，用coze工作流。

对于完全不想敲命令的同事，现在的AI Agent工具也能做这件事，比如coze平台上的工作流：上传一个Markdown文件，节点里配置一个文档转换插件，就能输出Word文档；一个工作流可以同时接入“文件解析、格式转换、内容摘要、导出链接”等环节。本质上它是在模拟“读取md文件->调用转换引擎->输出docx”的链路，只不过用可视化编排代替了命令行。

这条路的好处是，普通用户可以把手里的md文件交给工作流，一键产出Word；坏处是数据要经过第三方服务平台，敏感文档需要谨慎处理——这在哪里都是一样要注意的事。

6.3 流程图转换：从有道云到标准绘图语法的思路

“有道云Markdown转流程图”这个需求很有意思：有道云笔记里支持用代码块写流程图的语法，渲染出来是一张流程图形状。如果你想把它转换成其他平台能用的格式，本质上是把“某平台私有渲染语法”迁移成“通用绘图脚本”。

通用绘图脚本目前最常用的方案是Mermaid。它用类似Markdown的文本描述节点和连线，主流平台Win/macOS/Linux上都能渲染，GitHub的Markdown也原生支持Mermaid代码块。一个最简单的示例：

```mermaid flowchart TD A[开始] --> B{判断} B -->|是| C[结果1] B -->|否| D[结果2] ```

从有道云的流程图语法转换到Mermaid，核心是弄清楚源语法里每个字段的含义：哪个是节点文本、哪个是判断条件、哪个是连线方向。然后把它们映射到Mermaid语法里。这一步如果人工做，比较枯燥；如果你会一点Python，可以写个简单脚本去解析原始流程图代码块，逐行替换关键符号。思路就是“文本到文本”的规则转换，不需要复杂算法。

如果最终目标只是给别人看而不再编辑，那就不需要转换语法了——直接在支持Mermaid的编辑器里渲染成图片，导出PNG或SVG即可。我常用的做法是：在VS Code的Markdown Preview Enhanced插件里写好Mermaid，右键导出成PNG，然后再插入任何平台。这样流程图的“源头”始终是可维护的文本，图片只是产物。

6.4 Agent把网页保存成Markdown：自动化收藏夹的Skill思路

最后聊一个偏进阶但很实用的玩法：让Agent把网页保存成Markdown。

网上已经出现了不少“将网页保存成markdown的skill”，原理不算玄学，核心就是三步：抓取网页、提取正文、转成Markdown。真正有技术含量的是第二步“提取正文”——网页里有导航、广告、相关推荐，需要识别出哪部分是正文。很多实现会用一个叫“Readability”的算法，它跟浏览器阅读模式的原理类似：根据DOM结构层级、文本密度、链接密度来判断正文节点。

一个Agent Skill的实现思路大致是：

1. 输入：网页URL或HTML源码 2. 抓取：用HTTP客户端获取HTML 3. 清理：剔除script、style、nav、footer等非正文标签 4. 解析：用Readability类算法提取主内容DOM节点 5. 转换：将DOM节点按预设顺序转成Markdown标题、段落、列表、图片 6. 保存：输出为.md文件，图片本地保存或改用图床URL

如果你不想从零写，也可以在常见Agent平台上搜索“网页转Markdown”的现成Skill装进Agent，再配一条“抓取后保存到指定目录并重命名按日期归档”的指令，一个个人网页收藏夹就完成了。平时遇到一篇好文章，可以直接让Agent帮你存成Markdown进知识库，之后用Obsidian就能搜到。这个工作流，本质上和“markdown转word工作流”“有道云转流程图”是同一类需求：让Markdown在工具链里流动起来，而不是永远停在编辑器里。

我自己的习惯是，一旦某个格式或转换流程稳定跑通，就把它存成一个模板命令或小脚本，下次遇到相似需求直接套用。Markdown最大的价值不是语法本身，而是它作为一个“万能文本中间层”，能对接笔记、博客、代码仓库、AI工具和办公文档。你围绕它搭起来的工具链越顺，写作和归档的效率就越高。