标题用井号加空格表示,段落在源码里就是被空行隔开的连续文本行——这是 Markdown 最先要练的两个动作:井号定层级,空行定段落。掌握它们,你的文档就有了骨架。
在编辑器里输入下面的源码,注意井号后面必须有一个空格:
# 项目周报 ## 本周进展 功能开发按计划推进,接口联调完成八成。 ### 风险项 第三方依赖的配额下周一到期,需提前申请扩容。 ## 下周计划 完成剩余联调并提交测试。
渲染后你会得到一个清晰的三层结构:大标题、两个二级节、一个三级小节。两个要点值得立刻记住:
# 的数量决定层级,一级最大、六级最小,最多六个。#标题)在很多解析器里不是标题,只是普通文字——这是新手第一坑。# 一级 ## 二级 ### 三级 #### 四级 ##### 五级 ###### 六级
实际写作我建议止步于四级。五级六级在大多数主题里和加粗正文几乎没区别,层级深到那个地步,通常说明文档结构该拆分了,而不是继续加井号。
一个反直觉的事实:单个换行不产生新段落。试试这段:
第一行文字 第二行文字 空行之后才是新段落。
渲染结果里前两行会被合并成同一个段落(中间只有一个空格的距离),只有空行之后才算新段落。Markdown 的设计初衷是让源码在窄窗口下可以随意折行,段落边界交给空行判断。
如果你确实想让某行在同一段内强制换行,有两个办法:
办法一:行尾敲两个空格再回车(不可见,不推荐) 办法二:行尾放一个反斜杠再回车(部分解析器支持) 更现代的做法是直接用 HTML 换行标记,见第 3 章。
三个及以上星号或减号单独成行,就是一条水平分割线:
上一段内容 --- 下一段内容
⚠️ 常见坑:
---紧贴上一行文字且上一行是文字时,部分解析器会把那行文字识别成二级标题(Setext 式标题)。分割线前后各留一个空行最稳妥。
拿你手头任何一篇旧笔记,试着只添加标题,把它改成"一粗二细"的结构:一个一级标题做篇名,二级标题分节,最多局部用三级。你会发现标题其实是写作前的提纲——先写标题,再填正文,比写完再补结构轻松得多。
# 到 ###### ,对应一到六级;建议用到四级为止。---、*** 单独成行,前后留空行。骨架搭得好不好,主要看层级用得自律不自律。第一条纪律:一篇文档只有一个一级标题。它承担篇名的角色,出现两个一级标题,目录和锚点立刻混乱——不少静态站点生成器会直接把第一个一级标题之后的当成正文,后面的会破坏目录树。第二条:层级不许跳档。从二级直接蹦到四级,读者会下意识找"三级去哪了",多数渲染器虽然照常显示,但生成的文档大纲是残缺的。第三条:同级标题保持并列关系。同一层的标题应当是同类事物——"背景""目标""方案"可以并列,"方案"与"性能数据"就不该同层,后者是前者的小节。
判断层级是否健康,有个简单的自检:把文档里所有标题单独抽出来列成一张清单,只看这张清单能不能还原文档的逻辑。如果清单读起来像一份合理的提纲,层级就是健康的;如果出现孤零零的三级标题、同级标题粒度忽粗忽细,就该回去调结构。标题的另一个隐藏作用是锚点——渲染器会按标题自动生成页内链接,标题文字一旦改动,引用它的锚点全部失效。所以团队协作里倾向让标题措辞"写定就少改",需要频繁改措辞的小节,宁可多一层固定的上级标题来保护锚点稳定。
除了井号式(ATX)标题,Markdown 还保留了 Setext 式写法:文字下一行用 === 表示一级、用 --- 表示二级:
这是篇名 ======== 这是节名 --------
两种写法渲染结果一致,但工程实践里几乎全部选 ATX,原因有三。其一,Setext 只能表达两级,深层次结构还得混用井号,风格不统一;其二,--- 与分割线语法撞车,靠上一行是否有文字来区分,稍有不慎就误判——上一节那个"文字紧贴 --- 变二级标题"的坑正是由此而来;其三,很多静态站点和编辑器大纲面板对 Setext 支持不完整,折叠导航会漏掉这些标题。看一份陌生文档源码时能认出 Setext 即可,自己写则统一用井号。
编辑器里还有一个高频操作值得早练:用快捷键切换标题层级。VS Code 装 Markdown All in One 扩展后,Ctrl+]/Ctrl+[ 降升层级,Alt+Shift+上/下 整段移动;Obsidian 里则是 Ctrl+1 到 Ctrl+6 直接跳级,Ctrl+0 回正文。把手从井号键上解放出来,长文档调结构的意愿会高很多——结构懒得多调,往往只是因为手累。
改完结构后,用大纲视图自查:VS Code 的资源管理器底部有"大纲"面板,Obsidian 左侧可开"大纲",Typora 侧栏视图菜单里选"大纲"。大纲里如果出现灰色断档(比如三级直接挂到二级下却找不到同级兄弟),说明层级安排需要再想。养成发布前扫一眼大纲的习惯,比通读全文快得多,也更容易暴露结构问题。
下一节,我们让骨架上的某些字"跳出来"——强调与转义。
拿同一段内容做正反对照,体会层级规划的价值。反例:一篇排障笔记通篇只有三个二级标题"问题、过程、结论","过程"下面塞了十二段,关键转折淹没在段落海洋里。正例:把"过程"拆成"现象复现、定位路径、根因、修复"四个三级标题,每个三级标题下最多四段。读者找"根因是什么"时,正例三秒定位,反例需要通读。改造动作本身只花五分钟加四行井号,回报却是文档可查性的量级变化——这就是"骨架"这个词的本意:不是装饰,是检索路径。