企业官网建设流程全解析

我最早接触 Markdown，还是在写技术文档的时候。当时被 Word 的排版折磨得够呛，每次调格式都要花老半天，后来换成了纯文本的 Markdown，一下子就回不去了。这么多年下来，无论是写博客、记笔记、写 README，还是整理自动化脚本的说明文档，我几乎都离不开这层极简的标记语法。很多人一听"语法"两个字就头皮发麻，觉得又是 Python、C++ 那一套难啃的东西，其实 Markdown 的语法规则非常简单，认真学下来半小时足够，但它能帮你省下的时间，是往后每一篇文档、每一条笔记都会持续兑现的。

这篇文章就从基础用法讲到进阶工作流，把标题、换行、列表、代码块、图片路径这些最容易被坑的细节全部拆开说清楚，也会聊到数学公式、Callout、表格转 Excel、Markdown 转 Word 这些高频场景。不管你是刚接触 md 语法的纯新手，还是已经写了一阵子但总遇到格式问题的老用户，都可以照着里面提到的方案直接抄作业。

1. 为什么学 Markdown 而不是继续用 Word：核心思路与整体设计

1.1 语法的本质就是一套排版语法糖

学任何东西之前，先把"为什么"想明白，后面才不至于学完就忘。Markdown 这套语法规则的底层逻辑，就是用尽量少的符号，表达尽量多的排版意图。你可以把它理解成一种语法糖：原本在 Word 里要点击工具栏才能完成的加粗、标题、列表、引用，在 Markdown 里只要在文字前后加上**、#、-、>这些标记就够了。

如果你之前接触过 Python、Shell、C++、TypeScript 这些语言的基础语法，会发现它们都有一个共同特点：语法规则本身不复杂，难的是怎么组合起来解决实际问题。Markdown 也是一样，单个规则很简单，组合起来就能写出结构清晰、层次分明的文档。写 Markdown 的时候，你的手不需要离开键盘去摸鼠标，思路也不会被排版打断，这就是它最核心的吸引力。

1.2 适用范围比你想的更广

Markdown 不是程序员专属。我见过产品经理用它写需求文档，作者用它写书稿，学生用它做课堂笔记，运营用它整理选题库。只要是需要"纯文本承载结构化内容"的地方，它几乎都适用。

具体来说，我平时最常用的场景有这几类：

• 写技术博客和项目 README：GitHub、GitLab 对 Markdown 的原生支持非常完善，提交代码后文档自动渲染，省去部署博客系统的成本。
• 做个人知识库：Obsidian、Notion 这类笔记工具都支持 Markdown，笔记之间还能互相引用，比传统 Word 文档灵活太多。
• 写自动化脚本的说明文档：写完一个 Python 脚本或者 Shell 脚本，同目录下放一个README.md，把用法、参数、注意事项写清楚。很多时候 pipeline 脚本里也会用 Markdown 语法来生成报告文本，方便后续直接展示。
• 日常沟通和协作：在飞书、钉钉、语雀里，Markdown 语法大多能直接生效，尤其是代码块和列表，沟通效率提升非常明显。

1.3 一个统一的心智模型：用纯文本表达结构化内容

学 Markdown 最需要建立的，是一个统一的心智模型：你写的是纯文本，但通过特定符号，渲染引擎会把它变成带格式的页面。这个模型一旦建立，后面遇到任何不支持的功能，你都可以用最原始的办法解决——直接改文本标记，或者混入 HTML 标签。

比如你在某些不支持 Markdown 的平台上想要一个不一样的标题样式，可以直接写<h3>标题</h3>，大多数渲染引擎都会认。这种"纯文本为底、标记为骨"的设计，让 Markdown 能适应各种环境，也是它十几年经久不衰的根本原因。

2. 基础语法拆解与实操要点

2.1 标题、段落和换行的正确姿势

标题是最好学的，#的个数代表标题层级，一个#是一级标题，两个#是二级标题，最多六个#。注意#后面要加一个空格再写文字，否则某些渲染器不会识别。我见过不少新手在#标题这样写，结果怎么都不生效，其实就是差了一个空格的事。

段落更简单，一个空白行隔开就算另起一段。但这里有个超级常见的坑：单次回车不会换行。在大多数 Markdown 引擎里，你敲一个回车，渲染出来还是同一行；想要真正换行，有两种方式：

• 在行的末尾加两个空格，再按回车；
• 直接空一行，让文本成为两个段落。

第二种方式更常用，因为两个段落之间会有明显的间距，视觉上更清楚。还有一种特殊情况是 HTML 里的<br>标签，在某些不支持行尾空格的平台（比如部分论坛）很管用。

提示：在 Typora 这类所见即所得的编辑器里，单个回车会直接显示为换行，但导出到其他平台后可能就变了。所以最稳妥的做法，是养成"空一行分段"的习惯。

2.2 强调文字：粗体、斜体与删除线

强调语法是 Markdown 里最像"语法糖"的部分，记起来非常容易：

• 粗体：**文字**或者__文字__
• 斜体：*文字*或者_文字_
• 粗体加斜体：***文字***
• 删除线：~~文字~~

实际写作的时候，我个人建议统一用**和*，尽量避免__和_。原因很简单：下划线在文件名、链接文字、代码变量名里太常见了。比如你写_file_name_，本来想斜体，结果渲染出来可能整个乱掉。用*就没这个烦恼。

强调语法看起来不起眼，但用好了文档的阅读体验会提升一个档次。我的习惯是：加粗只用来标记真正重要的结论，斜体用来补充说明，删除线偶尔用在更新记录里，不要一句话里到处都是加粗，那样反而没有重点。

2.3 列表：有序、无序与嵌套任务

列表是 Markdown 里使用频率最高的语法之一。无序列表用-、*或者+开头，有序列表用1.、2.这种编号开头。这里有一个细节：有序列表的序号其实不需要你手动排正确，因为大多数渲染器会按顺序自动编号。所以你完全可以全部写成1.，渲染出来依然是 1、2、3。不过建议还是手动写对，因为有些平台导出时会读取原始数字。

嵌套列表的写法是子列表前缩进两个或四个空格。很多新手在这里出问题，缩进不一致导致层级错乱。我的经验是：嵌套列表必须用统一的缩进量，要么全部两个空格，要么全部四个空格，混着来必乱。

任务列表是 GitHub 风格的一种扩展，写法是在无序列表的基础上加上[ ]或[x]：

- [ ] 待办事项 A - [x] 已完成事项 B

这个语法在笔记软件里特别实用，我每天的工作清单就是用它管理的，勾选状态一目了然，而且纯文本备份下来也不丢信息。

2.4 引用、分隔线与转义字符

引用用>开头，可以嵌套，比如>是外层，>>是内层。引用块里可以放多个段落，只要每个段落前都加>就行。我写博客的时候经常用引用块放"注意""提示"这类文字，视觉上跟正文区分得很清楚。

分隔线是三个及以上的-、*或_，单独占一行。比如---或者***。这里有一个大坑：如果上一行是文字，再写---，会被误认为二级标题。因为 Markdown 里"文字加下划线"恰好是标题的另一种写法。所以写分隔线之前，一定要确保上面空一行。我自己的习惯是统一用---并且上下都留空行，出错概率最低。

转义字符可能很多人不知道，但它关键时刻救命。Markdown 里有些字符是有特殊含义的，比如*、#、>、[，你想在文档里直接显示这些符号，前面加一个反斜杠\就行：\*就能显示一个星号。我在写 Markdown 语法教学文档时，这一招是必须掌握的，不然没法在文章里展示语法本身。

2.5 插入代码：行内代码与代码块

写技术文档的人，几乎每篇都会用到代码。行内代码用一对反引号`包起来，比如`print("hello")`，适合在正文里提及某个函数名或命令。多行代码则用代码块，标准写法是三个反引号包起来，并在开头标注语言：

```python def hello(): print("Markdown 基础语法") ```

语言标注非常重要。它有两个作用：一是让渲染器做语法高亮，二是让某些平台（比如 GitHub）在代码块右上角显示复制按钮。常见的标注有python、bash、javascript、html、css、c++、typescript等。如果你不确定代码语言，也可以不标注，但高亮就没了。

另一种代码块写法是每行开头缩进四个空格，但这种方式不好维护，我基本不用，只在一些老旧的论坛系统里才会碰到。缩进式代码块有个坑：列表项里的代码块如果不额外缩进，层级就会乱，新手很容易在这里耗半天。

2.6 链接与图片：路径问题是重灾区

链接的语法是[显示文字](地址)，图片的语法是![替代文字](图片路径)，核心区别就是前面多了一个英文感叹号。替代文字很重要，图片加载失败时它就是占位符，屏幕阅读器也会读取它。

图片路径是 Markdown 新手问得最多的问题之一。路径分两种：网络 URL 和本地相对路径。写博客时用网络 URL 没问题，但本地笔记里如果乱写路径，换一台电脑或者移动文件后图片就全裂了。

我的建议是：

• 图片跟文档放在同一个目录下，引用时直接写文件名，比如![示例](example.png)；
• 如果放在子目录里，用相对路径，比如![示例](./images/example.png)；
• 绝对路径尽量别用，C:\Users\xxx\图片.png这种一旦换机器必挂，而且 Windows 路径里的反斜杠在 Markdown 里还有转义问题，很容易踩坑。

注意：路径里的空格要用%20或者调整目录命名习惯。最好的办法，是图片文件名从头到尾只用小写字母、数字、连字符、下划线，空格和中文名统一规避，能省掉大量莫名其妙的错误。

2.7 表格：写法与复制粘贴陷阱

Markdown 表格的语法基础是三部分：表头、分隔行、数据行。分隔行由|和-组成，还可以用冒号控制对齐方式。

| 功能 | 语法 | 说明 | | ---- | ---- | ---- | | 粗体 | `**文字**` | 加粗强调 | | 斜体 | `*文字*` | 倾斜强调 | | 删除线 | `~~文字~~` | 划线删除 |

表格看起来简单，实际操作时痛点不少。首先，单元格里如果包含|字符，需要用反斜杠转义为\|，否则表格结构会直接坏掉。其次，在手机上编辑表格特别痛苦，因为竖线不好打。我的解决办法是：先找一个在线表格转 Markdown 的小工具，把 Excel 或 WPS 里的数据粘贴进去，自动生成格式，再粘回笔记里。

还有一个高频场景：Markdown 表格复制到 Excel 会乱。这个问题我后面在常见问题部分会专门讲，这里先记住一个结论：表格要转 Excel，先转成 CSV，再用 Excel 打开 CSV，格式不会乱。

3. 从基础到进阶的实用工作流

3.1 选工具：Markdown 编辑器与阅读器

学完语法之后，第一个现实问题就是：用什么东西写、用什么打开.md文件。如果文件打不开，一切白搭。

先说明一个概念：Markdown 本质是纯文本，所以记事本、Sublime Text、VS Code 都能打开.md文件，看到的都是带标记的原始文本。但想要看到渲染后的效果，就需要专门的工具。

我按使用场景分三类推荐：

• 本地写作首选：Typora。所见即所得，写完就渲染好了，界面干净，对新手极友好。需要付费，但确实值。
• 程序员熟悉 VS Code：装一个 Markdown Preview Enhanced 插件，或者直接在Ctrl+Shift+V预览，基本够用。Sublime Text 也可以装 MarkdownEditing 和 MarkdownPreview 插件来查看，快捷键生成预览。
• 知识管理用户选 Obsidian：双链笔记、插件体系成熟，本地文件夹管理，非常适合长期积累笔记。

Linux 环境下，如果不想装图形界面程序，命令行里有glow、mdless这类终端 Markdown 阅读器，直接用glow README.md就能在终端里看到排版后的效果，写服务器文档时很方便。

如果你是纯新手，不知道 Markdown 编辑器怎么下载安装，我的建议是最简单的方式：先装 VS Code，免费、跨平台、插件丰富，以后写代码还能接着用。微信、知乎这类平台自带的编辑器一般也支持基础语法，可以先拿它们练手。

3.2 数学公式：用 LaTeX 语法插入公式

很多写技术笔记、论文草稿、学习记录的人，会遇到一个需求：Markdown 里怎么插入数学公式？其实 Markdown 本身不包含公式语法，靠的是外部渲染引擎支持 LaTeX 风格的数学公式代码。

常用的方式有两种：

• 行内公式：用$...$包裹，比如$E=mc^2$；
• 块级公式：用$$...$$包裹，公式单独占一行并居中。

行内公式示例：质能方程 $E=mc^2$。 块级公式示例： $$ e^{i\pi} + 1 = 0 $$

实际使用的时候，Typora、Obsidian、VS Code 的 Markdown 插件都原生支持这些公式。有些平台支持不到位，就需要借助 math 公式插件，关键词通常是MathJax或KaTeX。它们的区别是：KaTeX 更快，MathJax 兼容性更好。如果你只是写简单公式，KaTeX 足够；如果涉及复杂推导，选 MathJax 更稳。

3.3 GitHub 的 Callout 和高级扩展

如果你经常泡 GitHub，会发现很多 README 里有那种带颜色的提示框，看起来像引用块，但左边有不同颜色的边框和图标。这种语法叫 Callout，是 GitHub 对 Markdown 的扩展语法。

写法是在引用块开头加一个标识符，常用的是：

> [!NOTE] > 普通提示信息。 > [!TIP] > 实用小技巧。 > [!WARNING] > 需要注意的风险。 > [!CAUTION] > 可能导致严重问题。

这类语法的好处是信息层级特别清楚。我写项目 README 的时候，安装步骤用 NOTE，踩坑经验用 WARNING，安全注意事项用 CAUTION，读者扫一眼就能抓住重点。不过要注意：Callout 只被部分平台识别，如果你把文档发给不支持的人，渲染出来也就是普通引用块，不会报错，内容还在。所以可以放心用。

3.4 表格转 Excel、Markdown 转 Word 的实用路径

工作中经常碰到这样的场景：在 Markdown 里整理了一张表格，同事非要 Excel 版本。还有的团队内部习惯了 Word 文档，你写好的 Markdown 文档需要转成.docx发出去。

先讲表格转 Excel。最快的方法分两步：

1. 把 Markdown 表格粘贴到支持 CSV 导出的工具里，或者直接手动整理成 CSV 格式；
2. 用 Excel 打开 CSV 文件，另存为.xlsx。

如果表格特别多，建议用 Pandoc 或者在线转换工具，一步到位。Pandoc 的命令大致是：

pandoc input.md -o output.xlsx

注意：Pandoc 这里本质上也是先把表格提取出来再转换，遇到复杂表格可能有样式丢失，所以转完一定要抽查。

再讲 Markdown 转 Word。这又是一个高频需求，我自己的步骤是：

• 本地工具首选 Pandoc，一个命令搞定：

pandoc README.md -o 输出.docx

Pandoc 能自动识别标题层级、代码块、表格、图片，转换效果相当不错。没有安装 Pandoc 的话，可以先用 Typora 的导出功能，它自带 Word 选项，只是对复杂样式的控制没 Pandoc 那么细。

现在还有很多工作流平台支持自动化转换，比如在 Coze 这类平台里搭一个"Markdown 转 Word"的工作流，把文档丢进去自动生成 Word 再分发。适合需要大批量转换文档的团队场景。就我个人而言，单次转换还是 Pandoc 最省心。

3.5 把网页保存成干净的 Markdown

经常会有这种需求：看到一篇不错的网页文章，想保存到自己的笔记库里。直接整个网页存下来，又有一堆无关的导航、广告、推荐位，抓取正文转成干净的 Markdown 才是最佳方案。

这里推荐几个思路：

• 浏览器扩展：搜索"Save as Markdown"或者"Reader Mode"这类扩展，打开网页后一键保存，大部分扩展会自动提取正文和图片。
• 命令行工具：很多开发者写的小工具能把网页正文提取成 Markdown，配合 Python 脚本可以批量抓取保存。
• 自动化工作流：现在不少自动化助手都内置了"网页转 Markdown"的技能，你只需要输入 URL，它就能把网页正文整理成结构化的 md 文件。这类工具特别适合做信息收集和知识库沉淀。

我自己保存网页文章的时候，还会顺手处理一下图片：把图片下载到本地同目录，并把 Markdown 里的图片路径改成相对路径。这样就算原网页挂了，我的笔记里图片也还在。

另外，如果你在用 Python 写爬虫脚本，通常会先抓 HTML，用 etree 或者类似方式解析网页里的某个 body 块，再提取文本生成 Markdown。整个链路其实不复杂，但最终输出的 Markdown 质量，取决于你对正文区块的层级判断和清洗规则。建议保存后至少人工浏览一遍开头、代码块和图片区域，确认没有多余杂质。

4. 常见问题排查与避坑实录

4.1 换行为什么不生效

这是 Markdown 新手问得最多的问题，没有之一。核心原因前面提过：Markdown 的设计哲学是"一个回车不换行，空一行才是新段落"。很多人在 Word 里养成了一行一回车的习惯，到了 Markdown 里就觉得"怎么都挤在一起"。

解决办法分场景：

• 同一段落内想换行：行尾加两个空格再回车。
• 想另起一段：两行之间空一行。
• 想强制换行且不加段落间距：可以用<br>标签。

我还要补充一种情况：列表项内部的换行。如果想在列表项的下一行继续写文字，但不想让它变成新的列表项，需要在下一行开头补两个空格或按列表缩进对齐，否则渲染器会认为你新开了一个列表项。

4.2 图片显示不出来

图片裂了，十有八九是路径问题。排查顺序我一般是这样：

1. 先确认图片文件真的在对应目录下，文件名大小写对不对；
2. 再看路径是绝对路径还是相对路径，绝对路径在别的机器上必挂；
3. 检查路径里有没有空格、中文、反斜杠；
4. 最后看是不是网络图片被防盗链拦截，如果是，换成本地图片或者图床。

如果用的是 Windows，需要特别小心反斜杠\。Markdown 里反斜杠是转义符号，所以你写C:\Users\name\pic.png时，渲染器可能会把\U、\n这些组合当成转义字符，路径就废了。正确写法是改用/：C:/Users/name/pic.png，或者在反斜杠前面再补一层转义。

4.3 表格复制粘贴乱掉

把 Markdown 里已经渲染好的表格直接复制到 Excel，往往会变成一列、行错位、竖线乱蹦，这是因为 Markdown 表格在渲染后没有真实的行列结构，复制时 Excel 无法正确解析。

稳妥的方法是先转 CSV。操作步骤：

1. 把 Markdown 表格手动清理成 CSV 格式：逗号分隔单元格，换行分隔行；
2. 如果单元格里有逗号，用双引号包住整个单元格；
3. 用 Excel 打开 CSV，再另存为 xlsx。

批量表格建议直接用 Pandoc 或者在线 Markdown 表格转换工具，少受罪。

4.4 代码块失灵或高亮不对

代码块失灵通常有这几个原因：

• 三个反引号前后有空格或多余字符，导致闭合失败；
• 语言标识写错，比如把javascript写成js，部分渲染器可能不支持；
• 代码块里嵌套代码块时，内部的三个反引号没有用更多反引号包裹。

我在写 Markdown 教学文章时常遇到嵌套的问题——要展示一个包含代码块的代码块，最外层用四个反引号，里层用三个：

````markdown ```python print("嵌套示例") ``` ````

看起来绕，实际操作时这样处理就对了。

4.5 问题排查速查表

5. 写在最后的一点个人经验

Markdown 学了不会亏，这句话我这些年跟很多人说过，现在依然这么认为。它不像编程语言那样需要系统的数据结构、算法基础，也不像设计工具那样要研究视觉排版，它就是一个纯文本搭配一套极简符号，却能把你的写作效率实实在在地往上拉一截。

我个人在实操中有两个习惯，分享给你参考。第一，把常用语法做成自己的速查表，放在笔记软件里，写完忘了就打开查一眼。用得多了自然熟，根本不用死记。第二，尽量把 Markdown 文件放在一个长期稳定的目录结构里，图片统一放assets文件夹，文件名保持规范，这样等你的笔记积累到几千条的时候，依然能游刃有余。还有一个扩展方向：把 Markdown 作为输出格式，接入自己的工作流，比如用脚本批量生成周报、用网页转 Markdown 收藏资料、用 Pandoc 一键出 Word 版。等这些链路打通了，你大概就跟我一样，再也回不去 Word 手动排版的日子了。