企业官网建设流程全解析

Markdown 这个东西，我最早接触时以为它只是一个“给程序员用的记事本高级版”，后来真正用它写了两年技术文档、项目 README、课程笔记之后才发现，它其实是内容创作者和高强度文字工作者的效率底座。它不是软件，而是一种轻量级标记语言：用纯文本加少量符号来控制标题、列表、引用、代码块和表格的排版，最终可以渲染成网页、PDF、Word 等通用格式。跟着狂神的节奏把 Markdown 从零到进阶完整过一遍，你会发现它最大的价值不是“能排版”，而是让你彻底告别用鼠标反复调格式的动作，把精力完全还给内容本身。这篇文章适合刚接触 Markdown 的新手，也适合已经会基础语法、但总被图片路径、表格转换、公式显示折磨的老用户。我尽量按照实战顺序来讲，每个知识点都给出可直接照抄的写法。

1. 为什么要用 Markdown：它解决的不只是排版问题

1.1 写作与排版分离，专注内容本身

先想一个问题：你用 Word 写一篇十万字的方案，最多的时间花在哪？大概率不是想内容，而是在调格式：标题字号、行距、段落缩进、目录更新。Markdown 的思路反过来了，它强制你先用纯文本把结构写完，然后通过#号标记标题、*号标记强调、-号标记列表，排版交给渲染器去处理。我常用一个类比：Word 是边砌墙边刷漆，Markdown 是先把砖码好，最后统一交给装修队。这种方式最大的好处是，写作的时候你不会频繁被打断。注意力一旦从“内容”切到“样式”，再切回来，至少需要几分钟进入状态。长期写文档的人应该都有这种体会：格式操作越少，产出越高。

这种“分离”还带来了一个附加价值：同一份 Markdown 内容，可以在博客、GitHub、公众号、知识库、Word 文档之间无缝迁移，而不需要每次都复制粘贴再重新排版。你只需要改一下发布端的样式模板，内容一个字都不用动。这就是为什么技术圈里 README、接口文档、博客文章几乎都是 Markdown 格式的原因。狂神当时讲 Markdown 时反复强调过一个观点：语法是死的，习惯是活的。与其追求花哨插件，不如先把“纯文本写结构”这个习惯刻进肌肉记忆里。

1.2 纯文本带来的可迁移性与协作优势

Markdown 的底层是纯文本，这看起来“简陋”，但恰恰是它最大的优势。拿笔记软件举例，很多主流笔记应用都有自己的私有格式，你如果用了五年想换软件，导出、清洗、迁移会让人崩溃。但 Markdown 格式的笔记文件就是一个个.md文本文件，换任何工具都能打开，甚至用系统自带的记事本都行，不存在被某个厂商锁死的风险。

对于团队协作，纯文本还有一个隐藏属性：可以被 Git 这类版本管理工具逐行对比。谁改了哪句话、某个标题什么时候被删掉，都能清清楚楚看到，这在文档维护里非常实用。我见过很多团队把需求文档、技术方案直接用 Markdown 放在代码仓库里，和代码一起走评审流程，效果比在聊天工具里传 Word 文件高太多。当然，这种方案的代价是团队需要有一点“极客”习惯，但对技术团队来说几乎零成本。

2. Markdown 基础语法速查：从零写出第一篇文档

2.1 标题、段落、换行与强调：最常用的四个动作

标题在 Markdown 里用#表示，数量对应层级：一个#是一级标题，六个######是六级标题。这里要特别提醒：#和标题文字之间必须有空格，写成#标题在大部分渲染器里不会生效。一级标题通常留给文档名，不要轻易用，否则目录结构会乱。标题之后要空一行再接正文，否则某些渲染器会把标题和下一段当成一个整体，视觉层级会丢失。

段落之间要用空行分隔。同一个段落内如果直接回车换行，在大多数平台里并不会产生新段落，只会在部分渲染器里显示成空格。这是 Markdown 新手最容易踩的坑之一。想要真正的换行，有三种常见做法：一是段尾加两个空格再回车，这是 Markdown 原始规范；二是用<br>标签；三是干脆空一行分成两个段落。我个人的建议是：优先用空行分段，如果必须在同一段落里换行（比如表格里的多行内容），再考虑末尾两个空格或<br>。写博客、README 时，切莫只按一次回车就当换行，GitHub 上经常出现“明明写了多行，渲染后挤成一段”的尴尬。

强调语法也很简单：**加粗**表示粗体，*斜体*表示斜体，~~删除线~~表示带删除线的文字，==高亮==在部分平台表示高亮。注意这些符号都是成对出现，并且推荐写成两个星号包粗体而不是下划线，因为下划线在英文单词里容易误触发。如果你在写技术教程，行内代码要用反引号包起来，比如`git commit -m "init"`，这样渲染后会有代码样式，与普通文字区分明显。还有一个小技巧：某些平台支持用反斜杠转义 Markdown 符号本身，想直接展示#或*时，前面加一个\即可，比如\# 不是标题。

2.2 列表、引用、链接与图片：让内容更有结构

无序列表用-、*或+开头，有序列表直接用1.2.开头。这里有个细节：有序列表的数字其实不要求连续，渲染器会自动按顺序排列，但为了可读性，我仍然建议写成 1、2、3。列表嵌套时，子列表要缩进两到四个空格，不同编辑器要求的缩进不太一样，最稳妥的是用四个空格。如果你在列表项里写多行文字，注意保持首行后的行与列表符号对齐，否则缩进一乱，渲染结果可能直接断开。

引用块用>开头，可以嵌套，比如>加一个>>就是二级引用。在写博客或 README 时，引用块常用来放“注意”“提示”这类信息，视觉上非常清晰。我写文档的习惯是：普通说明用正文，需要单独强调的注意事项用>引用块，这样读者扫一眼就能抓住重点。

链接的写法是[链接文字](https://example.com)，图片的写法只比链接多一个感叹号：![替代文字](图片路径)。替代文字一定要写，一方面是在图片加载失败时给读者一个说明，另一方面方便屏幕阅读器朗读。如果在链接或图片地址里包含了空格、括号等特殊字符，整段地址最好用尖括号包起来，比如<https://example.com/a b>，否则部分渲染器会截断链接。

2.3 代码、表格、任务清单：效率控最常用的三件套

行内代码用单个反引号，代码块用三个反引号包裹，并且可以在起始反引号后写语言名称，比如：

def hello(): print("hello markdown")

这样渲染时就会有对应的语法高亮。代码块内部保留原始空格和换行，非常适合贴配置文件和命令。我还习惯在较长文档里给每个代码块加上语言标注，即使内容是纯命令也是如此，因为高亮能大幅提升可读性。要插入一个真正的反引号字符，可以用双反引号作为代码块的起始标记，这种技巧在写 Markdown 教程时尤其好用。

表格语法以管道符|划分列，第二行用---控制对齐方式：:---左对齐，:---:居中，---:右对齐。示例：

这里有个常见的坑：表格内容里如果包含管道符|，必须写成\|，否则会把当前单元格截断。表格中的换行也不能直接用回车，需要用<br>。另外，表格前后最好各空一行，特别是表格紧跟在标题或列表后面时，否则部分平台会解析异常。

任务清单是 GitHub 扩展语法，写法是- [ ] 未完成和- [x] 已完成。它特别适合用来写进度追踪类文档，比如上线检查表、学习计划。我试过把一周的工作计划全部写成任务清单，放在项目仓库里，每天更新勾选框，团队其他人一眼就知道哪些事还没做完。基础语法加起来就是这些，如果你能熟练运用，日常笔记和博客已经完全够用了。

3. 编辑器、阅读器与工具链：Markdown 文件要怎么打开才舒服

3.1 明确一件事：下载的不是“Markdown”，而是编辑器

网上经常有人搜“Markdown 下载”“Markdown 安装教程”，这里必须澄清一下：Markdown 是一种语法规范，不是一个可执行软件，所以你真正要找的是支持 Markdown 的编辑器。把.md文件用系统记事本打开当然也能看到内容，但那是纯文本，没有渲染效果，阅读体验很差。新手最舒服的路径是装一个所见即所得编辑器，边写边看到最终样式。

我推荐过的工具很多，目前的常用组合是这样：日常笔记用 Typora 或 Obsidian，写代码相关文档用 VS Code，需要最终输出 Word 或 PDF 时用 Pandoc 转换。Typora 的优点是界面干净，输入即预览，数学公式支持非常好；Obsidian 的优势是本地文件管理和双链笔记，适合做个人知识库；VS Code 本质是代码编辑器，但配合 Markdown Preview Enhanced 插件后，预览效果和自定义模板能力都很强，适合资深玩家。此外还有 MarkText、Zettlr 等开源选择，丰俭由人。不论选哪个，安装之后先新建一个.md文件把基础语法点一遍，确认预览正常再开始用。

3.2 各平台快速预览方案：Windows、macOS、Linux、Sublime

Windows 和 macOS 上最省事就是装 Typora，双击.md文件就能直接打开，不需要任何配置。如果你不想装独立软件，也可以用浏览器插件或者在线编辑器。Linux 用户则更适合命令行方案：glow是一个终端里的 Markdown 阅读器，输入glow 文件名.md就能看到带样式的渲染结果；mdcat类似但输出风格不同；如果想要更通用的方案，可以用 Pandoc 把 Markdown 转成 HTML，然后浏览器打开，命令是pandoc -s input.md -o output.html。这些工具在 Linux 包管理器里都能直接装，不需要额外配置。

再说一个很多人问过的场景：Sublime Text 怎么看 Markdown？Sublime 默认只是把.md当纯文本处理，需要先装 Package Control，然后搜索安装 Markdown Preview 插件，装好后用快捷键Ctrl + Shift + P，输入Markdown Preview，选择在浏览器中预览即可。配套的 MarkdownEditing 插件可以提供语法高亮，让编辑体验更接近专业 IDE。如果你是直接用 VS Code，装一个 Markdown Preview Enhanced 插件后，按Ctrl + Shift + V就能预览，非常顺滑。如果用的是 Vim，也有 vim-markdown 这类插件，但新手没必要在编辑器折腾上花太多时间，先有一个能用的预览环境就够了。

3.3 按使用场景选型的建议

工具不在多，够用就行。我的建议是：如果只是写个人笔记，选 Typora 或 Obsidian，打开文件即写即看；如果是程序员写 README、接口文档，VS Code 是底线；如果要做成团队知识库，考虑语雀、Notion 这类带云端协作的平台，它们同样支持 Markdown 语法；如果要把文档放 Git 仓库走评审，那就直接用任意编辑器，但提交前用 VS Code 或 GitHub 预览一遍。记住一点：不管选哪个工具，语法本身是通用的，换工具不换语法，这比任何花哨功能都重要。

4. 进阶实战：公式、图片路径、表格转换、网页转存的高频操作

4.1 数学公式支持原理与常用写法

很多朋友最初学 Markdown 就是为了写数学笔记和论文初稿。Markdown 本身不支持公式，但主流编辑器都会集成 LaTeX 公式渲染引擎，一般分为行内公式和块级公式。行内公式用两个美元符号包起来，比如$a^2 + b^2 = c^2$；块级公式用两对美元符号独占一段：

$$ \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} $$

这里能渲染的关键是编辑器内置了 MathJax 或 KaTeX。Typora 默认支持，不需要额外装插件；VS Code 的 Markdown Preview Enhanced 也支持，原生预览可能需要安装“Markdown+Math”扩展。常见的公式语法包括：上下标用x^2和x_i，分数用\frac{分子}{分母}，根号用\sqrt{}，求和用\sum_{i=1}^{n}，希腊字母用\alpha、\beta。如果你在某个平台发现公式显示为原始代码，先检查两边是不是有多余空格，再检查反斜杠是否被转义。渲染引擎对$和\比较敏感，这是最高频的问题，尤其是写完$$后一定要另起一行写公式，最后再单独起一行收尾，否则很容易不渲染。

4.2 图片路径的三种写法与踩坑记录

Markdown 图片路径有三种常见写法：网络 URL、相对路径、绝对路径。网络 URL 只要不失效就永远有效，但不适合离线文档；绝对路径从盘符根目录开始，比如C:\Users\...，只在你自己电脑上有用，一旦换机器或分享给别人就废了；相对路径是以当前文档所在目录为起点，比如./assets/photo.png，这是我强烈推荐的一种，配合规范的 resources 或 images 目录，整个文档目录可以随意整体搬移。

实操层面，Typora 在偏好设置里可以配置“复制图片到 ./assets”和“优先使用相对路径”，每次粘贴截图后它会自动把图片存进当前目录的子文件夹，并自动生成相对路径，这能解决 90% 的图片显示问题。VS Code 里可以装 Paste Image 插件，Ctrl + Alt + V直接粘贴剪贴板截图，默认存入当前目录的 images 文件夹。踩坑方面，最常见的是路径里带中文或空格导致渲染失败，尽量把文件名改成英文加数字；其次是在 Windows 上反斜杠\会被部分渲染器当成转义字符，路径分隔符尽量用正斜杠/。如果你处理的是大批量笔记，还可以考虑把图片转成 base64 内嵌，但这样会让文件体积剧增，只适合少量关键图。

4.3 表格转 Excel、Markdown 转 Word 的完整思路

表格处理是很多人实际工作里的刚需。从 Markdown 表格复制到 Excel 时，直接粘贴往往会把每一行当成一行文本，列对不上。正确姿势有三种：第一种是用 Pandoc 命令把 Markdown 表格转成 CSV，再用 Excel 打开；第二种是复制后粘贴到文本文件，然后在 Excel 里用“数据”菜单自文本/CSV 导入，并指定分隔符为管道符；第三种是干脆用 Python 的 pandas 读取，pd.read_csv('file.md', sep='|')后处理，但我很少这么干，因为大部分个人场景用前两种就够了。

Markdown 转 Word 也是一样，不要指望复制粘贴能保留样式。最可靠的是 Pandoc 命令：

pandoc -s input.md -o output.docx

这条命令会把标题层级映射成 Word 的内置标题样式，表格也会转成 Word 表格，代码块变成带底纹的段落。如果你没有接触过 Pandoc，可以把 Typora 的“导出 Word”选项当作替代方案，它底层调用的其实就是 Pandoc 或自定义转换逻辑。如果你想把整条链路自动化，现在不少低代码工作流平台也能处理这个需求：接收 Markdown 文本，调用 Pandoc 工具节点，生成 docx 后自动归档到云盘。核心注意点是，生成 Word 的节点必须真的调用文档转换引擎，否则只是把文本命名成.docx，打开就报错。至于有道云笔记里把 Markdown 转流程图，这是编辑器自带功能，入口在工具栏的流程图或画图菜单，插入后填写节点和连线即可，但流程图生成后在不同平台之间兼容性差，建议在文档里同时保留备用的文字说明。

4.4 把网页保存成 Markdown：从浏览器插件到 Agent Skill

遇到一篇好文章想存进笔记，但又不想复制乱糟糟的网页源码，于是“网页转 Markdown”成了高频需求。最简单的是浏览器插件，推荐 Markdown Web Clipper、简悦和印象笔记的剪藏功能。它们的思路类似：读取网页正文区域，过滤广告和导航，输出成干净的 Markdown，然后手动或自动存到本地或云端笔记。简悦还支持自定义解析规则，对结构复杂的页面更友好。

再进一步，这个动作也可以封装成一个 Agent Skill。我试过的流程是：给智能体一个指令“把当前页面存成 Markdown 并写入 Obsidian 目录”，它内部先读取网页正文，清洗标签，然后按照项目约定的模板输出标题、正文、链接、图片位置，最后写入.md文件。实现重点在于给智能体约定一套稳定的输出协议，比如标题使用#，正文段落之间空行，所有图片使用相对路径并下载到同目录 assets，遇到表格必须用 Markdown 表格语法。这种做法适合平时收集资料量大、需要固定格式的人，稍微配置一次，之后就是一句话的事。需要提醒的是，无论用什么方案，保存的都应是你有权访问和保存的内容，同时注意版权和合理引用。

4.5 GitHub 上的 Callout 提示块语法

如果你经常在 GitHub 上写 README 或项目文档，肯定见过那些带颜色的提示块。这其实是 GitHub 扩展的 Callout 语法，写法是在引用块的基础上加一个标签：

> [!NOTE] > 这是普通提示。 > [!WARNING] > 这是警告，需要注意高风险内容。 > [!CAUTION] > 这是严重警告，可能带来不可逆影响。

GitHub 目前支持的标签包括NOTE、TIP、IMPORTANT、WARNING、CAUTION，分别对应信息、贴士、重要、警告、严重警告。渲染后在页面上会显示不同颜色的框，非常醒目。这个语法的优点是纯文本可读，不依赖图片，缺点是只有 GitHub 等少数平台支持，在 Typora、语雀等编辑器里可能只会显示成普通引用块，所以不要把关键信息只放在 Callout 里，正文里的说明仍是必需的。

5. 常见问题与排查：我把自己踩过的坑都列出来了

5.1 换行不生效

这是新手问得最多的一个问题。原因通常是你直接按了一次回车，Markdown 认为这还不够形成新段落。排查思路是：先看渲染结果是否只是多了一个空格，如果是，就在段尾加两个空格或<br>，或者干脆把两段之间加一个空行。记住，不同平台的换行规则略有差异：在 Typora 里，用一个回车会被当成分段；在 GitHub 上，单回车不会换行，必须空一行或者用<br>。所以写文档的时候，我默认遵循“段间空行”规则，这样在任何平台都不会出错。

5.2 图片不显示

图片不显示九成是路径问题。先确认图片文件是否真的存在于你写的路径里，再确认是相对路径还是绝对路径，最后检查文件名里是否有中文、空格或括号。Windows 用户还有一个常见坑：路径里用了反斜杠\，在 Markdown 里\是转义符号，建议全部改成/。如果你用的是 Obsidian，还要注意附件路径设置是否和编辑器一致，不然本地看得到、换了设备就失效。实在排查不出来，把图片地址放到浏览器地址栏打开，看能否访问，能访问就是语法问题，不能访问就是路径问题。

5.3 表格复制到 Excel 乱、公式显示成源码

表格复制到 Excel 乱的原因是 Excel 没有识别管道符作为分隔符。解决办法前面已经说了，最稳的是用 Pandoc 转 CSV 或使用“自文本/CSV 导入”。公式显示成源码，基本是渲染引擎没开启或语法被转义。检查美元符号前后是否有空格，检查是否在代码块里写公式，检查编辑器是否支持 LaTeX。如果是公众号等平台，很多编辑器并不支持公式渲染，这时候可以把公式用图片代替，或者截图贴进去，虽然不优雅但能解决问题。

5.4 不同平台渲染差异可能造成“标准答案”不通用

Markdown 的底子虽然统一，但扩展语法和默认行为并不完全一致。GitHub 支持 Callout，Typora 有自己的一套目录和引用处理，语雀、有道云笔记又各有差异。所以我给团队和个人的建议是：核心文档只使用最基础的语法，也就是标题、段落、列表、引用、链接、图片、代码块、表格，这些在任何平台上都是最稳定的；花哨的扩展语法只在明确知道目标平台支持时才使用。这样写出来的文档才真正具备可迁移性。

我个人在实际操作中的体会是，Markdown 的上手曲线非常平缓，真正的分水岭在于你是否愿意在日常文档里坚持用它。我现在写任何长文档，都会先在 Markdown 里只写文字大纲，不碰任何样式，标题统一用##，等内容全部定稿后再回头调整层级和补充图片，最后用 Pandoc 导出 Word 或 PDF。这套流程看起来没什么技术含量，但真的帮我省了大量时间。如果你刚开始学，别急着把各种插件全部装上，先用系统自带的记事本写一个礼拜基础语法，再到编辑器里渲染，你会对 Markdown 的“纯文本”本质理解得更深。这大概就是跟狂神学的最大收获：不是背语法，而是建立一套高效率、可复用的写作习惯。