企业官网建设流程全解析

刚拿到一个新的 .md 文件时，很多人第一反应是双击打开，然后看到满屏的 # 和 *，第一反应是：这文件是不是坏了？我当年也一样，项目文档发过来，我以为是文本乱码，差点把文件删了。后来才知道，这其实就是 Markdown 编辑器最基础的入口问题——文件没坏，格式是纯文本标记，只是你还没找到顺手的渲染工具。作为一个把 Markdown 编辑器当主力写作工具用了快十年的老用户，今天想把这几年积累的选型经验、语法坑点、图片路径问题、数学公式配置、文档转换工作流，一次性梳理成一篇可以照着做的文章。不管你是刚接触 md 文件的新手，还是已经在 Sublime、Vim、VS Code 里折腾过的进阶用户，这里面应该都有你能直接抄作业的结论。

1. 先搞明白：Markdown 编辑器到底解决了什么问题

1.1 它不是排版软件，而是“纯文本 + 渲染”的组合

很多人把 Markdown 编辑器理解成“简化版 Word”，这么想就偏了。Word 这类富文本编辑器存的是格式化文档，你加粗一段字，背后是一堆样式信息；而 Markdown 编辑器存的是纯文本源文件，加粗就是用两个星号包起来，标题就是井号，列表就是横线或数字。真正渲染成什么样，要看最终谁来解析这行文本。这个理念让 md 文件具备了三个其他编辑器很难做到的特性：第一，任何电脑上都可以直接读取内容，不依赖特定软件；第二，Git 之类的版本管理工具可以逐行比对修改记录；第三，内容编辑和外观渲染彻底分离，写作时可以只关心内容结构。这也是我为什么把它当成主力写作工具的最根本原因——它逼你把注意力放在文字上，而不是字体字号上。

1.2 编辑器和编译器是两码事，这个坑要分清楚

“编译器和编辑器的区别”放在 Markdown 场景里特别好解释。编辑器是你的书写工具，负责把 Markdown 源码写出来；编译器或者说不那么严谨的“渲染器”，负责把源码转换成 HTML、PDF 或其他格式。这两个环节是独立的，所以同一份 .md 文件在不同地方打开，显示效果可能不一样：GitHub 有自己的一套渲染规则，Typora 是即时渲染，VS Code 的预览插件又是另一套实现。我踩过最典型的坑是：在 Typora 里辛辛苦苦排好的表格，推送到 GitHub 上发现列宽完全不对；还有在本地写好的高亮标记，到某个在线编辑器里直接显示成原始代码。理解了“编辑”和“编译”是两回事之后，遇到这种问题你就不会慌，先确认渲染环境支持哪些语法，再决定怎么写。

1.3 到底适合谁用，哪些场景值得切换

我的判断标准很简单：凡是内容大于排版、结构大于样式的写作任务，都值得切到 Markdown。典型场景包括技术博客、项目文档、接口说明、读书笔记、个人知识库、课程讲义，甚至邮件正文（有些客户端支持 Markdown）。程序员用它写 README 和文档是最合理的，因为代码天然就是纯文本；产品经理可以用它写需求说明，配合版本管理看 Diff 比 Word 优雅太多；学生做课堂笔记，用大纲和列表记录也远比截图和手打更快。反过来说，如果你要做的是一份需要非常精细排版、打印后分发给客户的正式合同或标书，那还是用 Word 更合适。Markdown 不是万能钥匙，没必要硬撑。

2. 编辑器选型：别纠结，按场景选

2.1 主流 Markdown 编辑器横向对比

很多新手上来就问“哪个 Markdown 编辑器最好”，其实没有最好，只有最顺手。我按使用场景把它们分成了四类，方便你对号入座。

第一类是即时渲染型，代表是 Typora 和 Mark Text。它们把源码和渲染结果合在一个窗口，你打上去的 Markdown 语法会立刻变成排版样式，适合追求所见即所得、不喜欢同时看两栏的人。第二类是知识库型，代表是 Obsidian 和思源笔记。它们本质上是“本地文件夹 + Markdown 文件”，同时附带双链、标签、反向链接，适合长期积累个人笔记和知识网络的人。第三类是代码编辑器型，代表是 VS Code、Sublime Text 和 Vim。它们本身不是 Markdown 专用工具，但通过插件可以获得完整的编辑和预览能力，适合本来就在写代码、不想再开一个软件的人。第四类是在线型，代表是 StackEdit、语雀、有道云笔记。浏览器打开就能写，多设备同步方便，适合临时写作、协作评审和轻量记录。

我整理了一个简单对比表：

2.2 新手推荐路径：先从最小可用的组合开始

我接触过很多新手，最容易犯的错误是第一天就装了一堆插件，然后被配置彻底劝退。我的建议是先走“最小可用”路线：本地随便选一个即时渲染工具，或者直接用在线编辑器把 Markdown 语法跑通；等真正需要代码高亮、多文件管理、文档导出的时候，再考虑加装功能。

安装这件事也要说一句。网上搜“markdown 下载安装教程”的时候，很容易点进下载站，然后装上来路不明的捆绑软件。我见过同事在 Windows 上装完某“全能编辑器”之后浏览器主页被篡改，卸载还卸不干净。所以下载时尽量去官网，或者用 Homebrew、apt、Windows 的包管理器安装，别碰那些“一键下载、绿色破解版”的按钮。来源不明的“全能文本编辑器”，十个有八个带有一堆你不想要的附加项。如果你只是临时打开一个 md 文件，也完全有更轻的路子：现在很多代码托管平台和笔记软件都提供网页版入口，把文件拖进网页就能预览，完全不污染系统。

2.3 我的个人使用演变史：从 Vim 到 Sublime 再到 Obsidian

工具选型的背后其实是习惯的演变，我分享一下自己的路径供参考。最早是纯命令行派，用 Vim 看代码时顺便看 Markdown，配置了 vim-markdown 插件。Vim 的好处是键盘流效率极高，写文档完全不离键盘；缺点是预览必须借助 grip 这类外部服务，对于要频繁看图、看表格的场景不够直观。后来转到 Sublime Text，装了 MarkdownEditing 和 LiveReload，左边写右边浏览器自动刷新，体验好了不少，但它本质上还是源码编辑，不能满足“边写边看到排版”的需求。真正让我稳定的组合是：主力写作用 Typora，笔记库用 Obsidian，代码仓库里的 README 和设计文档用 VS Code。三个工具各有各的位置，谁也别想替代谁。

3. 核心语法和高频坑点：这些细节决定你的文档好不好用

3.1 换行的真相：为什么明明回车了却还是连在一起

“markdown 换行”这个坑，几乎每个新手都会踩。你在一行文字后面按了回车，结果渲染出来发现跟下一行还是连着的，很多人第一反应是“编辑器坏了”。其实 Markdown 的标准规则是：普通回车叫软换行，很多渲染器里它只表示源代码换行，不产生段落换行；真正要段落分明，需要在两段之间留一个空行；如果只是想在同一段落里强制换行，就要在行尾加两个空格再回车。这个规则不是某个编辑器自定义的，而是 Markdown 规范本身就有的，只不过不同编辑器处理松紧不同。我推荐的写法是：段落之间一律用空行分段，别依赖两个空格这种看不见的字符；如果遇到某些编辑器空行后间距过大，那就调整渲染主题，而不是去改语法。

3.2 插入代码：行内代码和代码块的使用边界

“markdown 插入 code”也是高频操作。行内代码用单个反引号包起来，比如引用函数名或文件路径；代码块用三个反引号围起来，并在开头标注语言类型，比如 markdown、python、bash，渲染器就会自动语法高亮。需要注意两个小坑：第一，如果你的代码里本身包含三个反引号，围栏代码块会被提前截断，解决办法是增加反引号数量，比如用四个反引号包住；第二，缩进式代码块用的是制表符或四个空格开头，这在某些渲染器里会被错误识别，所以我统一建议用围栏式代码块，规则更清晰。还有一点，如果你在文档里写 LaTeX 公式，记得代码块的语言标注别写坏，否则高亮引擎会把反斜杠吃掉。

3.3 表格：写起来容易，复制到 Excel 才是大坑

Markdown 表格语法本身不难：第一行写表头，用竖线分隔列，第二行用横线分隔表头和数据，后面再写数据行，还能用冒号控制列对齐。真正头疼的是“markdown 表格转换 excel”和“markdown 表格复制”这两个需求。直接把渲染后的表格复制到 Excel，很多情况下粘贴出来是一列，所有单元格都堆在一个格子里，因为渲染后的 HTML 表格没有换行符，Excel 不知道该怎么分列。我的做法分两种情况：如果只是几个小表格，直接在 Markdown 源码里把竖线替换成逗号，得到 CSV 格式再导入 Excel；如果是大表格，用在线表格转换工具，或者用 Pandoc 转成 docx 之后从 Word 里复制，效果稳定得多。另外单元格内要写竖线字符本身，必须用反斜杠转义，否则表格列会被截断。

3.4 图片路径：为什么图片在本地好好的，发出去就没了

“markdown 图片路径”和“编辑器添加图片不显示”这两个问题，说到底是同一个根因：图片的引用地址没有指向一个稳定可达的位置。Markdown 图片语法是惊叹号加方括号加括号，括号里写图片地址，这个地址可以是相对路径、绝对路径、URL，也可以是 base64 数据流。绝大多数人遇到“编辑器里添加图片不显示”，是因为相对路径的基准目录不一致：在 Typora 里相对路径是相对于当前 .md 文件所在目录，而在某些代码编辑器或 HTML 页面里，相对路径可能是相对于项目根目录或网页地址。我的建议是给每个文档项目定一个统一规则，比如根目录下建一个 assets 文件夹，图片全部放进去，md 文件统一用“assets/文件名”这种相对路径去引用；发布到网站或 GitHub 时，要么用图床外链，要么把图片一并提交到同一层级。别用绝对路径，换一台电脑就废了。

3.5 常用语法速查：从标题到列表到引用

为了照顾刚上手的朋友，我把最常用的一组语法放在这里。标题用一到六个井号加空格表示，一级标题就是一个井号；有序列表用“数字 + 点 + 空格”，无序列表用“横线 + 空格”或者“星号 + 空格”；加粗用两个星号包住，斜体用一个星号；引用用大于号加空格；分割线用三个以上横线或星号独占一行。这些基础符号不需要死记，用多了自然就熟了。真正需要警惕的是那些“长得像语法但不是语法”的写法，比如行首数字加句号有时候会被识别成有序列表，又比如大于号开头的内容必须空一行才不会被当成引用。宁可写简单一点，也不要为了花哨引入渲染器不支持的特殊写法。

4. 进阶工作流：数学公式、Callout、网页抓取和文档转换

4.1 数学公式插件：LaTeX 公式在 Markdown 里怎么落地

写技术文档经常要插入数学公式，这就涉及“markdown 数学公式插件”。Markdown 本身没有公式语法，靠的是渲染层接入 MathJax 或 KaTeX。Typora 和 Obsidian 都内置了公式支持，VS Code 需要在插件市场装 Markdown Preview Enhanced 或 MathJax 插件。语法也很直观：行内公式用美元符号包裹，比如 $E=mc^2$；块级公式用双美元符号独立成行。热词里提到的“markdown 大括号多行公式”，在 LaTeX 里用 cases 环境，例如分段函数的写法：f(x) = \begin{cases} x, & x > 0 \ 0, & x = 0 \ -x, & x < 0 \end{cases}。这里要注意反斜杠的转义问题，还有下划线在公式里表示下标，如果没在公式环境中直接写“_”，有些渲染器会把它误判成斜体标记。我的习惯是公式多的时候，先用 Typora 或者 VS Code 预览确认渲染正常，再提交到 GitHub，因为不同平台的公式插件加载速度和支持范围有差异，GitHub 偶尔会出现公式延迟加载的情况，这是平台缓存造成的，不是你的语法写错了。

4.2 GitHub Markdown 的 Callout 语法：给文档加醒目的提示块

GitHub 上的 README 和 issue 里经常能看到那种带颜色的提示框，这不是靠表格或引用块硬凑的，而是 GitHub 专有的 callout 语法。写法是在引用块第一行写“> [!NOTE]”或“> [!WARNING]”这样的标记，后面接内容，渲染出来就是一个带图标的提示卡。常见类型有 NOTE、TIP、IMPORTANT、WARNING、CAUTION 五种，适配不同强调程度：NOTE 适合补充背景信息，TIP 适合给改进建议，IMPORTANT 适合关键依赖，WARNING 适合潜在风险，CAUTION 适合可能导致失败的严重问题。要注意的是，这个语法在 GitHub 站内渲染支持得很好，但在 Typora、VS Code 的某些插件里可能只会显示成普通引用块，不会出现彩色框。我写跨平台文档时会提前确认目标平台，如果主要发布在 GitHub，就用 callout；如果还要本地导出 PDF，就老老实实用引用块加粗文字，避免渲染不一致。

4.3 把网页保存成 Markdown：Agent 和扩展工具都很能打

很多人看到好文章想存到自己的笔记库里，直接复制网页进 Word 会带着一堆广告和乱格式，而“agent 将网页保存成 markdown 的 skill”这几年特别流行。最简单的方案是浏览器扩展 MarkDownload，打开网页点一下，正文就会被提取成干净的 Markdown 文件；进阶一点可以用命令行工具 Pandoc 配合 Readability，把网页正文抽出来再转成 md；现在还有一些 AI 助手和 Agent 的 Skill，输入一个 URL，它会把页面内容结构化整理成带标题、代码块和表格的 Markdown 笔记。我实际用下来最稳定的组合是：浏览器上装 MarkDownload 做快速保存，重要长文用 Readability 抽正文之后交给 AI 整理摘要和知识点。这种方法比单纯复制粘贴好太多，存档进 Obsidian 之后找资料非常方便。不过有一点要注意：很多网站的版权声明和反爬限制，个人存档没问题，别拿去做公开再分发。

4.4 Markdown 转 Word/PDF：Pandoc 一行的力量

“markdown 转 word 工作流”在办公场景里问得很多。核心工具就是 Pandoc，一条命令搞定格式转换：pandoc in.md -o out.docx，转换出来的 Word 文档自带标题层级，表格也是真表格，比复制粘贴整洁太多。转 PDF 需要额外装 LaTeX 引擎，嫌麻烦的话可以先用 Markdown 渲染成 HTML，再用浏览器打印成 PDF。流程图这块，Markdown 本身不包含绘图能力，但可以通过代码块写流程图方言，比如 flowchart 风格的 mermaid 语法，或者用 PlantUML，然后在有道云笔记、GitHub 等支持渲染的地方显示成图。我自己搭过一条 Coze 的工作流：从输入一个 Markdown 文件开始，自动提取大纲、拼接模板、导出 Word 并生成封面，全程不需要手动操作。对经常要出周报和方案的人来说，这比每次都人工排版省力得多。

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

5.1 “markdown 文件怎么打开”速查表

这个问题每天都有新人问，我给一张实用速查表：

记住一个原则：.md 文件本质是文本文件，任何编辑器都能打开看源码；想要看渲染效果，才需要渲染工具。

5.2 图片不显示的排查现场

我遇到“编辑器添加图片不显示”时，通常按这样的顺序排查。第一步，看图片文件和文档的相对位置，确认路径写法对不对；第二步，检查文件名里有没有中文、空格或括号，这类字符在部分渲染环境里会出问题，尽量改成英文小写加连字符；第三步，确认你是从哪个基准目录写路径的，Typora 和 VS Code 的基准可能不一样；第四步，如果是从网页或 HTML 编辑器粘贴进来的图片，确认是不是 base64 内嵌，太长时某些编辑器会截断；第五步，用图床外链的话，看是否存在防盗链和跨域问题。多数情况卡在第二三步，路径问题超过一半。我自己遇到过最离奇的一次，是图片文件名以数字开头，在某个旧版渲染器里被当成了有序列表的延续，整段图片直接消失。

5.3 装了太多编辑器、想卸载又搞不定怎么办

这里顺带说一个被问得很多的问题：“全能文本编辑器卸载”和“编辑器打不开”。我的建议是：凡是没有官网、只有各种下载站推广的“全能编辑器”，大概率是风险软件，卸载时优先用系统的卸载程序，然后查一遍浏览器主页和开机启动项。至于编辑器本身打不开，常见原因有配置冲突、插件版本不兼容、权限不足。VS Code 打不开时，可以清空设置目录或者用命令行 code --disable-extensions 排查；Typora 打不开通常是授权过期或配置文件损坏，删除配置文件夹即可恢复默认。遇到这类问题别忙着重装系统，先查配置、再查插件，最后才考虑重装，效率会高很多。很多“策略组编辑器打不开”之类的问题，本质也都是权限和组件损坏，修起来思路大同小异。

5.4 跨平台渲染差异：为什么同一个文件在两个地方长得不一样

最后一类常见问题是渲染不一致。同一份 Markdown，在 GitHub、Typora、VS Code、有道云里可能差很多，原因是各家对标准语法之外的元素支持力度不同。比如 GitHub 不直接支持 HTML 标签里的部分样式，而 Typora 支持；某些在线工具不渲染数学公式，显示成源码；表格宽度和引用块样式也各有各的偏好。我的经验是：写文档前先明确最终发布到哪，以那个平台的渲染为基准做适配，并尽量避免用太冷门的扩展语法。如果非要跨平台，就只用标准语法加上 GitHub callout 这种兼容性高的写法，冷门功能宁可牺牲也不冒风险。

从踩坑到形成自己的写作习惯，我大概用了两年时间。现在我的固定工作流是：写作和笔记用 Obsidian，项目仓库里的文档用 VS Code，需要对外交付时用 Pandoc 转 Word 或 PDF；图片统一放 assets 目录，路径全用相对路径；公式多的文档，先开启 LaTeX 渲染确认没问题再推送。这套流程稳定运行很久，基本不再遇到图片不显示或表格粘贴乱的情况。如果你刚开始接触 Markdown 编辑器，我的建议是先别急着装齐所有神器，把换行、表格、图片路径这几个基础规则吃透，再谈进阶；工具没有最好的，只有你用得上、用得顺的那个。