企业官网建设流程全解析

Markdown这东西，我接触了快十年，从最早写技术文档觉得HTML太啰嗦，到后来写周报、写方案、写知识库、写课程笔记，几乎每天都要用。很多朋友问我："这玩意和Word到底啥区别？"我一般就回一句：一个让你专注内容，一个让你折腾格式。这两年Markdown的普及程度已经很高了，不少笔记工具、在线文档、代码托管平台都原生支持，学好了你就是走到哪写到哪，一份文件到处用。这篇文章不打算把语法手册给你从头抄一遍，而是从实际使用的视角，把核心语法、工具选型、踩坑经验、常见问题一次讲透。不管是刚入门的新手，还是已经用了几天但总在细节上犯迷糊的朋友，看完应该都能少走不少弯路。

1. Markdown到底是什么，为什么偏偏是它

1.1 一个被误解很深的轻量级文本规范

很多人第一次见到Markdown，会以为它是一门编程语言，或者觉得它只是"程序员用来写README的工具"。这个理解不算错，但格局小了。Markdown本质上是一套纯文本的排版约定，它用几个特殊符号来表示结构：井号是标题，星号是强调，破折号是列表。你用记事本都能写，不依赖任何特定软件。

为什么这套"符号约定"能火起来？因为它解决了写作里一个很隐蔽但特别折磨人的问题：格式和内容强耦合。用Word的时候，你想把标题改成三级标题，要点半天鼠标，还得担心样式哪天不小心弄乱了；想换个主题，所有手工调过的地方全得跟着改。Markdown把选择权交回给内容本身，你只需要用符号告诉解析器"这是标题、这是列表、这是链接"，最终呈现在什么样式，由主题和渲染器决定。想换风格？换套CSS就行，正文一个字不用动。

我自己的体会是，Markdown最值钱的地方不是"能排版"，而是"让你形成写作节奏"。写过东西的人都有这种感觉，思路顺的时候，停下来点鼠标选字体是特别打断心流的事。用Markdown，手可以不离开键盘，想到哪写到哪，格式符号顺手就带上了，写完一渲染，版式整齐得像请了排版员一样。

1.2 谁最需要学，学了能用在哪儿

这个问题我每年都会被问几次。说实话，Markdown的适用面比你想的要宽得多。

写技术文档和代码笔记的人，应该学。这类场景要求结构清晰、代码块标注明确、能托管在版本管理工具里，几乎就是给Markdown量身定的。做产品、运营、行政的同学，也建议学。日报、周报、项目总结、会议纪要，这些文档本身不需要复杂排版，但需要结构清爽。用Markdown写完，直接导出PDF发出去，或者粘贴到支持Markdown的在线文档里，效果比纯文本好一个量级。

还有一大类是知识管理。现在很多笔记工具都基于Markdown，比如老牌的某笔记软件、某双链笔记工具，它们内部存储的底层格式就是Markdown。你如果想从A工具迁移到B工具，最平滑的路径就是让笔记以Markdown格式保存，因为它是纯文本，迁移永远不会遇到格式错乱。那些用私有格式保存的笔记，换工具时导出经常丢图片、丢高亮，迁一次你就再也不想迁了。

一句话总结：只要你有"需要长期维护、反复整理、跨设备查看"的文字材料，Markdown就是性价比极高的选择。

2. 从零上手：核心语法与编辑器的取舍

2.1 这套一看就懂、一用就忘的基础语法

Markdown上手真不难，难在"用对"。我把高频语法拆成几类，你直接照着写就行。

标题是写作的骨架，写法是一个到六个井号加空格，对应一级到六级标题。注意井号和标题文字之间那个空格不能省，省了有些解析器就不认了，这是我见过最多的新手上手坑之一。

强调和粗体，星号或下划线都能用。单个星号是斜体，两个星号是粗体，两个波浪线是删除线。很多编辑器还支持两个等号包住文字做高亮，但不是所有平台都认，跨平台要注意。

列表分无序和有序。无序列表用减号、星号、加号加空格开头都行，有序列表就是"数字. 空格"。实战里重要的不是怎么写，而是嵌套：子列表要在父列表下一行，缩进至少两个空格或一个Tab，否则渲染出来平级，层级就乱了。这个问题在笔记软件里最常见，因为它的列表识别常有自己的规则。

链接和图片的语法几乎一模一样：方括号写文字，小括号写地址。图片就是链接前面多一个感叹号，小括号里除了地址还能写"可选提示文字"。区别就一个：链接是人点一下跳转，图片是直接渲染出来。

代码分行内和块级。行内代码用一个反引号包住，块级代码用三个反引号包住，反引号后面还可以写语言名，比如bash、python、javascript。写上语言名有两大好处：渲染时获得语法高亮，看起来专业；复制代码的人不会被颜色干扰。我强烈建议写代码块时都标一下语言，哪怕只有一行，也标。

引用段落用大于号开头，可以无限嵌套不推荐。表格则是纯粹的"悲壮记忆"：第一行表头，第二行是分隔线加对齐标记。基础表格就这么写：

第二行那三个短横线是表格的"身份印章"，少了这一行，解析器就不知道上面是表头还是普通内容。

2.2 语法里那些反直觉的细节，得单独记

上面说的是"标准操作"，下面这些属于"不加注意就要踩坑"的细节，我用实际教训换来的。

第一，空行是段落的分界。Markdown里一个换行不算段落结束，两个换行才算。你想让文字分成两段，中间必须空一行。有时你写一篇文章，渲染出来全都挤在一起，十有八九就是换行没空行。有的编辑器给回车默认插入一个空行，有的不给，所以换编辑器后这种问题特别明显。

第二，列表和代码块打架的问题。你在列表里想放一段代码块，直接在列表下一行写三个反引号，渲染出来代码块会跑到列表外面去。正确做法是代码块整体缩进，跟列表内容对齐。类似的还有引用块里放列表、列表里放引用，本质都是嵌套，核心原则就一条：子级内容要比父级多缩进。缩进不对，层级全乱，这是Markdown排版里最消耗耐心的坑。

第三，标题层级跳跃不好看但不报错。你从一级标题直接跳到三级标题，解析器不会拦你，但大纲会变得很丑，给人一种"作者排反了"的感觉。强烈建议标题层级按顺序往下走，一级下面用二级，二级下面才用三级。

第四，图片大小控制是个老大难。基础Markdown语法不支持设置图片宽高，很多新手在写文档时想给图片加个宽度参数，到处查怎么写。实际上标准语法就是写不了，你需要借助HTML标签，或者依赖特定编辑器的扩展语法。如果你主要发布到某个平台，建议把图片尺寸在编辑平台里调好再粘贴，或者直接用HTML的img标签控制。后面我会专门讲。

2.3 编辑器三选一：轻量、所见即所得、全能

工具选型是Markdown学习里特别影响幸福感的一环，问十个老用户能给你推荐出十套组合，但总结下来就三条路线。

第一类是极简纯文本路线，代表是系统自带记事本、代码编辑器。它免费、通用、启动快到飞起，但左侧码字右侧看不到预览，对纯新手不友好。你写半天，渲染出来什么效果全靠脑补，格式错误了也不容易发现。

第二类是所见即所得路线，代表是各种专注Markdown的写作软件。这类工具的卖点是你在界面上直接看到最终排版效果，不需要记太多符号，快捷键就能加粗、设标题，还能直接拖拽图片上传。对刚入门的人来说，这类工具学习成本最低，也是我建议大多数新手的起点。

第三类是全流程路线，代表是代码编辑器加预览插件。既能写、能预览、能看大纲、能搜索替换，还能装各种插件搞定导出、拼写检查、标签跳转。如果你打算把Markdown变成长期主力工具，或者要处理成百上千个笔记文件，建议往这条路线上靠。代码编辑器本质是"文件管理器加编辑器"，所有文件都是本地文件，不依赖云端，数据安全感强得多。

选型建议很简单：第一步，先用所见即所得软件把Markdown语法真正用起来，形成习惯；第二步，当你发现需要批处理文件、需要自定义导出模板、需要批量替换图片路径时，再切换到代码编辑器路线。一上来就逼自己用纯文本编辑器，容易劝退。

3. 让文档好看、好用：主题、导出与资源管理

3.1 一套顺眼的主题，直接决定你愿不愿意写

Markdown渲染出来的默认样式，说好听叫"克制"，说难听叫"寡淡"。纯白背景、黑色文字、蓝色链接，功能上没毛病，但长时间盯着写东西，眼睛确实容易累。这就涉及主题和CSS了。

HTML标签加CSS做网页结构的应该秒懂：Markdown解析后变成HTML，CSS定义它的外观，主题就是一整套预置CSS。笔记软件、所见即所得编辑器大多提供主题中心，能换字体、换背景色、换代码高亮配色。我见过有人在笔记软件里调的深色主题，配上绿底代码块，长时间写文档眼睛一点都不干涩。

如果你用的是代码编辑器路线，自定义CSS更是家常便饭。你可以写一个很简单的样式文件，把正文行高设为1.8，标题间距调大，代码块背景换成淡灰。这样所有Markdown文件渲染出来都是统一风格。我自己的做法是维护一份通用主题文件，换电脑、换工具都不慌，导入主题就是三分钟的事。

有个细节容易忽略：预览窗口的CSS和导出PDF的CSS经常不是一套。你在预览里看着挺舒服，一导出PDF，字体变回默认宋体，间距全变。解决方法是把导出配置里单独指定样式，或者直接基于同一个CSS做一套导出专用版，多花点时间，但效果稳定多了。

3.2 图片路径、跨设备同步，这俩问题最拖后腿

图片是Markdown写作里最让人头疼的模块，没有之一。Markdown图片其实就是一个相对路径的引用。你把图片放在docs/images目录下，文章里写![示意图](images/架构图.png)，预览就能显示。

但这里头有几个坑。第一，相对路径是相对于当前文档所在文件夹的。你写images/xxx.png，前提是images文件夹和当前文稿在同一层级。如果稿子挪到子目录，图片路径全要改。第二，跨设备同步容易出幽灵问题。你在A电脑上的本地路径能显示图片，把文件同步到B电脑后，如果目录结构不确定，图片就挂一片。第三，把Markdown文件发给别人，图片不会跟着走，对方看就是一堆破图。

我用的策略是"集中式图片目录"。整个笔记库建一个统一附件文件夹，或者按文章名建同名子目录，起名规则固定。这样迁移时整体复制，图片路径大多不用改。再进阶一点，可以引入图床，图片传到线上拿到公网地址，文章里直接用URL引用。好处是好文到处发、到处都能渲染；坏处是图床挂了图片就永久丢失。我见过有人把笔记图片全放免费图床上，某天图床停止服务，整个知识库变成文字加破图，那种绝望我再不想经历第二次。

比较稳的做法是重要文档用本地图片目录加同步盘，公开分享的内容才用图床。本地是源，线上是副本，源不能丢。

3.3 导出PDF、Word和微信公众号，三套方案

Markdown写起来爽，但交付的时候世界不是围着你转的。同事要Word版，领导要PDF版，公众号要排版漂亮的图文，这三件事各有各的麻烦。

导出PDF，最简单的是用编辑器的内置导出功能。所见即所得软件一般有"导出为PDF"按钮，效果基本等于打印预览。想要更好看的页边距、页眉页脚，就用浏览器打开渲染后的HTML文件，按Ctrl+P调出打印窗口，在打印设置里选"另存为PDF"。这种方法高度可控，纸张大小、缩放比例、背景图形都能调，还能自定义。

导出Word，标准Markdown不支持直接存成docx，但基本所有主流编辑器都内置了导出Word功能。导出的文档结构还在，但样式不一定跟你的Word模板一致。如果你所在单位的Word模板要求特别严格，建议先导出基础版，再在Word里微调页眉页脚，别指望一步到位。

发布微信公众号，这个场景很多人会遇上。公众号编辑器对Markdown不友好，直接粘贴文本格式会乱。目前通用做法是找个在线排版工具，把Markdown原文粘贴进去，选套样式，再复制预览结果到公众号后台。这些工具的底层逻辑就是用CSS预先设计好样式，把Markdown渲染成美观的图文。你只需要记住：样式不要贪多，公众号的排版核心理念是留白够、行距舒服、重点突出，花里胡哨的配色反而拉低阅读体验。

4. 实战踩坑：那些渲染失败的典型案例

4.1 空行不对，全文挤成一团

我帮同事排查过一个特别诡异的现象。他的Markdown笔记在电脑上一切正常，同步到平板上用另一个软件打开，段落间距就全乱了。排查半天发现，源头是换行习惯。他在电脑编辑器里习惯按回车直接换行，编辑器自动把单换行当成了段落分隔。但换了工具后，解析规则变成"单换行只是软换行，双换行才是新段落"，于是全文全挤在一起。

这就是我前面反复强调的：空行是段落的灵魂。跨工具、跨平台使用时，最保险的写法是段落之间严格空一行，不要依赖编辑器的智能识别。养成这个习惯，你的文档到哪儿都不会乱。

4.2 列表嵌套错乱，大纲像鬼画符

有一次我写项目说明，在二级列表下缩进写了三级列表，渲染出来三级列表跑到跟二级列表并列的位置，整个层级完全失控。后来仔细看才发现，缩进我用的是空格，但某个子列表我多打了一个空格，解析器就认为它是一个新的列表级别。

列表嵌套的教训是：缩进必须严丝合缝地统一。要么全用Tab，要么全用固定数量的空格，混着用必出问题。如果你发现列表序号从某个位置开始重新计数了，大概率就是缩进不一致导致解析器认为你开了一个新列表。

4.3 表格和代码块混排，配置里最常出的错

代码块里如果包含三个反引号，会把外层的代码块提前终止。比如你想在Markdown里展示"如何写代码块"，需要在最外层代码块里用四个反引号包裹，或者用波浪线替代三个反引号，算是以矛攻盾的骚操作。

表格里放代码块就更麻烦了，因为代码块是多行结构，表格要求一行一个格子，天然不兼容。遇到这种情况，我一般不用表格，改成在列表下方放代码块，结构反而更清楚。这就引出一个小原则：Markdown的每种语法都有自己的脾气，不要强行把它们揉在一起，合理拆分展示结构，比追求"一个元素搞定所有"聪明得多。

4.4 中文标点被"智能处理"成乱码

某些所见即所得编辑器有自动纠正功能，会把半角引号自动替换成全角引号。这在写普通文章时挺贴心，但如果你在代码块里写代码，自动替换会把代码里的字符串引号改坏。我遇到过代码里明明写的是英文双引号，复制出来变成中文引号，运行直接报错。

解决办法是进编辑器设置，关闭代码块内的自动纠错。如果编辑器不支持单独关闭，那写代码块时小心，写完检查一遍引号和括号。

5. 常见问题速查与排查思路

下面这张表是我这几年被问得最多的问题汇总，基本覆盖了新人常踩的项目。

排查思路上，我习惯先定位"是语法问题还是环境问题"。语法问题特征是同样内容在不同工具里表现不同，环境问题往往是所有内容在一个工具里都表现异常。前者去查写法，后者去查设置或版本。另一个技巧是：文件夹里放一个"语法检查.md"，把每种语法都写一段作为标准样例，换工具时先用它验证渲染效果。这个文件能帮你快速排除"到底是我写法不对，还是工具不认"这个千古谜题。

再补一个容易被忽略的点：先转义再展示。你想在文档里展示一个真实的星号而不是把它当成斜体标记，需要在这个符号前面加反斜杠。比如写*不是斜体*，渲染出来就是一对普通的星号。这个技巧用的不多，但一旦写"语法教程"这类文字，几乎必然要用。

6. 常被忽略但真的有用的进阶能力

6.1 锚点与内部跳转：长文档的导航神器

标题除了排版，还有一个隐藏身份：锚点。一些编辑器默认会给每个标题生成一个ID，你可以在文内构造链接跳转到指定标题，形成目录效果。比如文末写"回到开头"四个字，给它挂上链接指向开头标题的锚点，点击就能跳回去。

具体写法是链接地址填"#标题文字"，不过不同工具对锚点ID的编码规则不一样，有的是自动转小写、转空格为短横线。建议你在自己常用的工具里测试确认，因为锚点跨工具迁移时经常会失效。我的习惯是长文档结构化写作时，顶部手工写个目录区，用锚点链接把各章节串起来，对阅读体验的提升非常明显。

6.2 任务清单与折叠语法：项目管理也能干

Markdown的任务清单语法是普通列表的扩展，写法是- [ ] 未完成和- [x] 已完成。这个语法用途比想象中大得多，不只是记待办。我常用它写发布清单：调研、初稿、配图、校对、发布，每步一个勾选框，一篇文章做到哪一步一目了然。知识整理也是好场景，把读书笔记改成清单体，每个问题一个勾选，打勾的过程特别解压。

部分工具还支持折叠块语法，把一个段落收进可展开的区块里。拿来放长代码、放详细说明、放备份的旧内容特别有用，页面显得干净，需要的时候展开就能看到。折叠语法的格式通常是<details>和<summary>包裹，这已经属于HTML混编的范畴了，但在很多工具里都是支持的。

6.3 模板化与自动化：把写作变成流水线

Markdown最被低估的能力，其实是可以格式化和自动化。你写日报周报，可以准备一个模板文件，标题、日期、完成事项、明日计划都预设好，每天复制一份填空就行。你写产品文档，把一级二级标题、必填段落全部搭好框架，后续只需要往里填内容，格式永远不会因为手滑而变乱。

更进一步是跟脚本结合。虽然Markdown不是编程语言，但它是纯文本，可以用批处理批量替换模板里的占位符，可以用脚本把多个Markdown文件拼成一个总文档，甚至放在持续集成流程里自动构建文档站点。这对知识库维护、团队文档管理来说，是实打实的生产力提升。我个人最深的一个体会是：写一百个零散的笔记很简单，难的是把它们组成一个可以长期维护的知识体系，Markdown的纯文本属性让这件事变得格外顺手。

最后再分享一个小技巧，也是我自己常用的习惯：定期把手里的Markdown文件全量备份一遍。它其实就是一堆文本文件，可以打包、可以进Git、可以存网盘，恢复起来几乎零负担。这种对数据完全掌控的踏实感，是很多花里胡哨的格式软件给不了你的。