企业官网建设流程全解析

1. 为什么我劝你认真花两小时把 Markdown 语法吃透

很多人第一次接触 Markdown，是在写 GitHub 的 README 文件，或者用 Typora、Obsidian 记笔记的时候。当时觉得这玩意儿不就是加几个符号吗，能有多难？结果真到用的时候，表格对不齐、换行不生效、图片路径挂掉、列表嵌套乱成一锅粥，各种问题全冒出来了。我见过太多人写了半年笔记，还在用空格手动对齐表格，还在疑惑为什么回车了预览里没换行。

Markdown 这门标记语言的核心价值就一句话：让你用纯文本的方式，写出结构清晰、排版规整的文档，而且这份文档在任何平台、任何编辑器里都能保持可读性。它不像 HTML 那样标签冗长，也不像 Word 那样格式和内容绑死。你写的是一个.md文件，但它可以变成网页、PDF、Word、幻灯片、电子书，甚至可以直接渲染成带流程图的富文本页面。

这篇文章适合谁看？如果你是程序员、技术写作者、笔记爱好者、博客博主、项目文档维护者，或者你只是单纯想知道“md 文件用什么软件打开”“markdown 表格怎么转 Excel”这类具体问题，那这篇内容基本能覆盖你 95% 以上的日常使用场景。我会从最基础的语法规则讲起，一路讲到表格转换、HTML 互转、编辑器选型、图片路径管理、换行坑点这些实战细节。不夸张地说，你把这篇看完并且跟着敲一遍，以后写文档的效率至少翻一倍。

下面我按“设计思路 → 核心语法细节 → 实操全流程 → 常见问题排查”这个顺序来展开，每一块都会告诉你“为什么这么设计”以及“实际用的时候要注意什么”。

2. Markdown 整体设计思路与语法体系拆解

2.1 为什么 Markdown 要用“符号+空格”这种设计

Markdown 的发明者 John Gruber 当初设计它的目标非常明确：让文档在纯文本状态下就具备可读性，同时又能方便地转换成结构化的 HTML。这个目标决定了它的语法设计哲学——用最少的符号表达结构，而且这些符号在纯文本里看起来也不能太丑。

你注意观察一下，Markdown 的所有语法几乎都遵循一个规律：符号 + 空格 + 内容。比如# 标题、- 列表项、> 引用、1. 有序列表。这个空格非常关键，它不是可有可无的装饰，而是解析器判断“这是语法”还是“这是普通文本”的核心依据。我踩过好几次坑，写#标题没有空格，预览里就是一段普通文字，根本不给你渲染成标题。

为什么这么设计？因为如果不需要空格，那你在正文里写“C#语言”或者“#话题标签”的时候，解析器就会误判。加上空格这个约束，就大幅降低了歧义。这个思路和很多编程语言的语法糖设计是一样的——用一点点书写成本换取解析的确定性。

另外，Markdown 是宽松语法，不同解析器（CommonMark、GFM、Markdown Extra 等）对同一段文本的渲染结果可能有细微差异。比如 GitHub 用的是 GFM（GitHub Flavored Markdown），它支持表格、任务列表、删除线、自动链接，而标准 Markdown 原生是不支持表格的。所以你写 md 的时候，最好先确认你的目标平台用的是哪套规范。

2.2 块级元素与行内元素的区别，这是理解一切语法的基础

Markdown 的语法元素可以分成两大类：块级元素（Block-level）和行内元素（Inline）。这个分类直接决定了你的换行、嵌套、缩进行为，不理解这个，后面全是坑。

块级元素包括：标题、段落、列表、引用、代码块、表格、水平分割线。它们的特点是独占一行或多行，前后会自动产生换行。行内元素包括：加粗、斜体、删除线、行内代码、链接、图片。它们的特点是嵌在段落文字中间，不会打断段落流。

为什么这个区分重要？举个例子，你想在列表项里放一个代码块，如果不知道缩进规则，代码块就会跑出列表外面。再比如，你想在表格单元格里换行，直接用回车是不行的，得用<br>标签。这些都是块级和行内规则在起作用。

提示：记住一个原则——块级元素可以嵌套块级元素和行内元素，行内元素只能嵌套行内元素。违反这个原则，渲染结果就会出乎意料。

2.3 常用 Markdown 解析器与规范差异对照

这张表你在选编辑器或者写跨平台文档的时候一定要心里有数。比如你给 GitHub 写 README，用 GFM 的语法完全没问题；但如果你把同样的文件丢到一个只支持 CommonMark 的解析器里，表格就会变成一堆竖线文本。

3. 核心语法细节逐项拆解与实操要点

3.1 标题、段落与换行：最基础也最容易翻车的地方

标题语法用#表示，一级标题一个#，二级两个，最多支持六级。写法是# 标题内容，井号后面必须有一个空格。我建议一篇文章只用一个一级标题，就是文章标题，然后二级、三级依次往下排，这样结构最清晰。

段落就是普通文本，段落之间必须空一行，解析器才会认为是两个独立段落。如果你只敲一个回车，大多数解析器会把它当成同一段落内的换行，渲染出来还是连在一起的。

这里就是最大的坑：Markdown 里单个回车不等于换行。你想在预览里真正换行，有两个办法。第一个是在行尾加两个或以上空格然后回车，这叫“硬换行”。第二个是直接写<br>标签。实测下来，行尾双空格在很多编辑器里会被自动清理掉（比如保存时格式化），所以我现在一律用<br>，稳定可靠。

这是第一行<br> 这是第二行，用了 br 标签强制换行 这是新段落，前面空了一行

注意：如果你用 VS Code 写 md，建议打开markdown.preview.breaks设置，开启后单个回车也会渲染成换行，但这会导致你的文件在其他平台渲染结果不一致，跨平台文档慎用。

3.2 列表与嵌套：缩进规则决定一切

无序列表用-、*或+，有序列表用1.2.3.。同样，符号后面要有空格。有序列表有个很方便的特性：你全部写1.，渲染时会自动按顺序编号，不用手动维护数字。

嵌套列表的规则是：子列表相对于父列表项要缩进 2 到 4 个空格。不同解析器对缩进量要求不一样，CommonMark 规定是 2 个空格起步，但为了兼容性，我一般用 4 个空格或者一个 Tab。这里有个细节，如果你用 Tab 缩进，有些编辑器会把 Tab 转成 4 个空格，有些转成 2 个，所以团队协作时最好统一用空格。

- 第一层列表项 - 第二层列表项，缩进 4 个空格 - 第三层列表项 - 回到第一层

列表里放代码块，代码块需要缩进到和列表内容对齐的位置，通常是 8 个空格（父列表 4 个 + 代码块 4 个）。这个很容易搞错，我建议你直接在编辑器里试一次，看预览效果调整。

3.3 代码块与行内代码：写技术文档的命根子

行内代码用反引号包裹，比如`code`。如果代码本身包含反引号，就用双反引号包裹，比如``code with ` backtick``。

代码块用三个反引号开头和结尾，并且在开头的反引号后面标注语言类型，这样能触发语法高亮。比如：

```python def hello(): print("Hello Markdown") ```

标注语言类型这件事很多人偷懒不写，结果代码块全是灰蒙蒙一片，阅读体验差很多。支持的常见语言标识有python、javascript、bash、json、sql、html、css、java、go、rust等等。你写redis学习笔记md的时候，里面如果有 Redis 命令，就标bash或者redis，高亮效果很好。

代码块里如果本身要显示三个反引号，就用四个反引号包裹外层，这是嵌套规则。

3.4 表格语法：从对齐到转 Excel 的完整方案

表格是 Markdown 里最容易写错的部分。基本语法是这样：

| 姓名 | 年龄 | 城市 | |------|------|------| | 张三 | 25 | 北京 | | 李四 | 30 | 上海 |

第二行的------是分隔行，必须有。冒号控制对齐：:---左对齐，:---:居中，---:右对齐。不写冒号默认左对齐。

实际写的时候，源文件里表格列宽不需要对齐，渲染时会自动处理。但为了源文件可读性，我建议你用编辑器插件自动格式化表格，VS Code 里Markdown All in One插件就有这个功能，快捷键一按，竖线全部对齐。

关于markdown 表格转换 Excel，这是热搜里很多人问的。最稳的办法是：先把 md 表格复制到 Typora 或者 VS Code 预览里，然后直接复制渲染后的表格，粘贴到 Excel 里，行列会自动对应。如果你要批量转换，可以用 Pandoc 命令行：

pandoc input.md -o output.xlsx

或者用 Python 的pandas读 md 表格再写 Excel。我实测下来，Pandoc 对复杂表格（单元格内有换行、合并）支持一般，简单表格完全够用。

3.5 链接、图片与路径管理：90% 的图片挂掉都是路径问题

链接语法是[显示文字](链接地址)，图片语法是![替代文字](图片地址)。图片前面多一个感叹号，这是唯一区别。

图片路径是重灾区。路径分两种：相对路径和绝对路径。相对路径是相对于当前 md 文件的位置，比如./images/pic.png或者../assets/pic.png。绝对路径是完整的 URL 或者系统路径。

我强烈建议：在项目里建一个images或assets文件夹，所有图片放里面，md 里用相对路径引用。这样整个项目文件夹拷贝到任何地方，图片都不会丢。如果你用绝对路径，换台电脑就全挂了。

另外，md 支持 img 标签吗？支持的。你可以直接写<img src="./images/pic.png" width="300">，这样还能控制宽高，比原生语法灵活。但注意，有些极简解析器不渲染 HTML 标签，会把它当纯文本显示。GitHub 是支持 img 标签的，放心用。

提示：图片文件名尽量不要用中文和空格，用英文加连字符，比如markdown-table-demo.png。中文文件名在某些服务器和解析器上会出现编码问题，导致图片加载失败。

3.6 引用、分割线与任务列表：提升文档结构感的小工具

引用用>，可以嵌套，>>就是二级引用。引用里可以放其他块级元素，比如列表、代码块。分割线用三个或以上的-、*、_单独一行，比如---。

任务列表是 GFM 的扩展语法：

- [x] 已完成任务 - [ ] 未完成任务

这个在 GitHub Issue、项目 README 里特别常用。注意方括号里x表示勾选，空格表示未勾选，x大小写都可以。

4. 完整实操流程：从零写一份规范的 md 文档

4.1 编辑器选型：不同场景用不同工具

md 文件用什么软件打开、md 编辑器怎么选，这取决于你的使用场景。我按场景给你列一下：

如果你问我个人最常用什么，我日常是 VS Code 写、Typora 预览、Pandoc 导出。VS Code 的好处是它同时是代码编辑器，写redis学习笔记md这种带代码的文档特别顺手。

4.2 用 VS Code 编辑 md 文件的完整配置流程

第一步，装 VS Code，这个不用多说。第二步，装插件。我必装的三个插件是：Markdown All in One（快捷键、目录、格式化）、Markdown Preview Enhanced（增强预览，支持流程图、数学公式）、Paste Image（截图直接粘贴成图片并自动生成路径）。

第三步，配置。打开设置，搜索markdown，把Markdown › Preview: Breaks勾上（如果你需要单回车换行），把Editor › Word Wrap设为on（长行自动折行，不然写表格要横向滚动）。

第四步，建项目结构。我一般这样组织：

my-project/ ├── docs/ │ ├── README.md │ ├── guide.md │ └── images/ │ ├── demo1.png │ └── demo2.png └── src/

第五步，写内容。用Ctrl+Shift+V打开预览，边写边看。用Ctrl+Shift+P调出命令面板，输入Markdown All in One: Create Table of Contents可以自动生成目录。

4.3 HTML 与 Markdown 互转的实操方法

html转为md这个需求很常见，比如你从网页复制了一段内容，想转成 md。方法有几种：

第一种，用在线转换工具，搜“HTML to Markdown”就有一堆，适合零散内容。第二种，用 Pandoc：

pandoc input.html -o output.md

第三种，用 Python 的html2text库：

import html2text h = html2text.HTML2Text() h.ignore_links = False with open("input.html", "r", encoding="utf-8") as f: html_content = f.read() md_content = h.handle(html_content) with open("output.md", "w", encoding="utf-8") as f: f.write(md_content)

反过来，md 转 HTML更简单：

pandoc input.md -o output.html --standalone

--standalone参数会生成完整的 HTML 文档，包含<!doctype html> <html lang="zh-cn"> <head> <meta charset="utf-8">这些头部信息。如果你不加这个参数，只生成 HTML 片段，需要自己套模板。

注意：Pandoc 转换时，md 里的 HTML 标签默认会保留。如果你不想要，加--strip-comments或者用-t markdown过滤。

4.4 打包多个 HTML 与 md 文档的批量处理

有时候你需要把多个 md 文件合并成一个，或者把多个 HTML 打包。合并 md 最简单：

cat chapter1.md chapter2.md chapter3.md > book.md

但这样合并会丢失章节间的分页和目录。更好的办法是用 Pandoc 的多文件输入：

pandoc chapter1.md chapter2.md chapter3.md -o book.html --toc --standalone

--toc会自动生成目录。如果你要打包多个 HTML 成一个，可以用pandoc先把 md 合并再转 HTML，或者用脚本把 HTML 片段插入到一个模板里。

我做过一个项目，把 20 多篇 md 笔记合并成一本电子书，流程是：先用脚本给每个文件加统一的标题层级，然后用 Pandoc 合并转 HTML，最后用wkhtmltopdf转 PDF。整个流程跑下来不到 5 分钟，比手动复制粘贴快太多了。

5. 常见问题与排查技巧实录

5.1 Markdown 换行不生效的三种原因与解法

这是被问得最多的问题。原因一：只敲了一个回车。解法是行尾加两个空格或者用<br>。原因二：编辑器自动清理了行尾空格。解法是改用<br>或者开启编辑器的breaks选项。原因三：解析器不支持硬换行。解法是检查你的目标平台规范，CommonMark 是支持行尾双空格的，但有些老解析器不支持。

我现在的习惯是：正文段落之间空一行，段落内需要换行的地方一律用<br>。这样不管在哪个平台，渲染结果都一致。

5.2 表格渲染错乱的排查清单

表格不渲染，通常有这几个原因：分隔行缺失或格式不对（必须是|---|---|这种）、表格前后没有空行、单元格里的竖线没有转义（用\|）、表格列数不一致。我整理了一个速查表：

5.3 图片不显示的排查思路

图片挂掉，按这个顺序查：第一，路径对不对，相对路径是相对于 md 文件还是工作目录（不同编辑器行为不同）。第二，文件名大小写对不对，Linux 服务器区分大小写。第三，图片格式支不支持，webp 在部分老解析器里不支持。第四，图片是不是被 gitignore 了，导致没上传。第五，如果是网络图片，检查链接是否失效、是否有防盗链。

我踩过最坑的一次是：本地预览正常，推到 GitHub 上图片全挂。原因是图片文件夹名用了大写Images，但 md 里写的是小写images，Windows 不区分大小写，Linux 区分。改过来就好了。

5.4 不同编辑器渲染结果不一致怎么办

这个问题的根源是解析器规范不同。解法是：统一用 CommonMark 或 GFM 作为基准，然后在目标平台上测试。如果你写的是 GitHub README，就在 GitHub 上预览；如果你写的是博客，就在博客后台预览。不要只在本地编辑器里看，本地编辑器可能用了自己的扩展语法。

另外，VS Code 的 Markdown Preview Enhanced 插件支持切换解析器，你可以在设置里指定用 CommonMark 还是 GFM，这样预览结果更接近目标平台。

5.5 独家避坑技巧汇总

第一个技巧：用注释标记待办。md 支持 HTML 注释<!-- 这里待补充 -->，渲染时不会显示，但你自己能看到。我写长文档时经常用这个标记需要回头补的地方。

第二个技巧：用<details>标签做折叠内容。GitHub 支持这个标签，可以把大段日志、长代码折叠起来，让文档更清爽。

<details> <summary>点击展开详细日志</summary> 这里放长内容 </details>

第三个技巧：用锚点做文档内跳转。标题会自动生成锚点，链接写法是[跳转到标题](#标题名称)。注意中文标题的锚点在不同平台处理方式不同，GitHub 会把中文转成拼音或者保留中文，建议用英文标题或者手动加<a name="anchor"></a>。

第四个技巧：表格转 Excel 时先转 CSV。如果 Pandoc 直接转 xlsx 有问题，可以先转 CSV，再用 Excel 打开 CSV 另存为 xlsx，成功率更高。

pandoc input.md -o output.csv

第五个技巧：用markdownlint检查语法规范。VS Code 装markdownlint插件，它会实时提示你哪里语法不规范，比如标题层级跳跃、列表缩进不对、行尾多余空格等。团队协作时统一开启，能避免很多格式争议。

6. 进阶场景：让 Markdown 覆盖更多工作流

6.1 Markdown 转 Word 的自动化工作流

markdown转word工作流是很多写作者的需求。最直接的是 Pandoc：

pandoc input.md -o output.docx --reference-doc=template.docx

--reference-doc可以指定一个 Word 模板，这样导出的文档会套用模板里的样式（字体、字号、页边距）。如果你需要自动编号，可以在 md 里用有序列表，Pandoc 转 Word 时会保留编号。但如果你要复杂的多级编号（比如 1.1、1.1.1），建议在 Word 模板里定义好样式，Pandoc 会按标题层级套用。

我实测下来，Pandoc 转 Word 对表格和图片支持很好，但代码块的高亮会丢失，变成普通等宽字体。如果你需要保留高亮，可以先转 HTML 再转 Word，或者用 Typora 直接导出 Word。

6.2 Markdown 与 Mermaid 流程图结合

markdown preview mermaid support这个热搜词说明很多人想在 md 里画流程图。Mermaid 是一种用文本描述图表的语法，GitHub、GitLab、Typora、VS Code（装插件）都支持。

```mermaid graph TD A[开始] --> B{判断条件} B -->|是| C[执行操作] B -->|否| D[结束] ```

注意，Mermaid 的渲染依赖平台支持。GitHub 原生支持，VS Code 需要装Markdown Preview Mermaid Support插件，Typora 需要开启设置。如果你把 md 转到其他平台，Mermaid 代码块可能不渲染，所以重要流程图建议同时导出图片备份。

6.3 Markdown 在笔记系统中的应用

redis学习笔记md、python基础语法这类学习笔记，用 md 写是最合适的。我的笔记结构一般是：一个总目录README.md，然后每个主题一个文件夹，文件夹里一个index.md加若干子文档。用 Obsidian 的话，可以用双链[[文档名]]互相引用，形成知识网络。

笔记里的代码块一定要标语言，方便以后搜索。比如你搜```python就能找到所有 Python 代码片段。另外，用标签#redis#python做分类，比文件夹更灵活。

6.4 Markdown 浏览器扩展与阅读器推荐

如果你只是想在浏览器里看 md 文件，装一个Markdown Viewer扩展就行，Chrome 和 Edge 都有。它能把本地 md 文件渲染成网页，还支持自定义 CSS。md 浏览器扩展的好处是不用装桌面软件，临时看个文件很方便。

阅读器方面，Typora 是最舒服的，但它是付费的。免费替代品有MarkText、Obsidian（免费个人使用）、Zettlr。如果你只需要看不需要编辑，直接用 VS Code 预览就够了。

7. 我个人的 Markdown 使用心得

写了这么多年 md，我最大的体会是：语法本身很简单，难的是养成规范书写的习惯。很多人学会了语法，但写出来的文档还是乱，因为不注重空行、不标语言、不用相对路径、不检查渲染结果。

我现在写任何文档，都会先花 30 秒搭好结构：一级标题、二级标题、三级标题列出来，然后再填内容。表格和代码块写完一定在预览里看一眼。图片一律放images文件夹，用相对路径。需要换行的地方一律用<br>。这套习惯养成之后，文档质量稳定很多，也很少出现“本地正常、线上挂掉”的情况。

另外，不要追求花哨的语法。Markdown 的核心价值是内容结构化，不是排版炫技。我见过有人用一堆 HTML 标签和 CSS 把 md 搞得像网页一样，结果换个平台全乱了。保持简单，保持兼容，这才是 md 的正确用法。

最后分享一个我最近常用的技巧：用pandoc加--toc和--number-sections参数，可以自动生成带编号的目录，导出 PDF 或者 HTML 都很好用。命令是：

pandoc input.md -o output.pdf --toc --number-sections --pdf-engine=xelatex -V CJKmainfont="Microsoft YaHei"

CJKmainfont指定中文字体，不然 PDF 里中文会变成方块。这个坑我踩过，折腾了半天才找到原因。