5.3 Markdown 与文档编辑装备

5.3 Markdown 与文档编辑装备

本节摘要：写文档占工程师工作的相当比重，值得独立整备。本节搭起 Markdown 的"编辑增强、实时预览、规范检查"三位一体：快捷键加列表续行管编辑，预览与大纲导航管浏览，检查器管规范；再配表格编辑与图片粘贴两件小装备。整备后的工位里，文档享受与代码同级的编辑体验。

传动轴装好，工具墙的下一组挂件服务另一类产出：文档。设计文档、接口说明、问题排查记录、周报——工程师的输出里文字占比惊人，而多数人给代码配齐了装备、给文档却只有裸编辑。这一节把文档台也整备起来，编辑、预览、检查三位一体，顺带说明：本册教程本身就是这套装备的产物。

适用场景：为什么文档值得单独整备

信号很普遍：写列表要手敲星号与横线、调整标题层级靠数井号、表格对不齐要数字符、贴张图要先另存文件再手写引用、文档写完无人检查格式规范。这些都是"裸编辑"的摩擦。文档的读者往往是更多人（评审者、未来的自己），格式混乱的代价比代码格式混乱更外显——值得同等对待。

编辑增强：让标记隐形

主力装备是 Markdown 增强套件（社区公认的那件全能型），装上后标记语法"隐形化"：加粗斜体走快捷键、列表与引用自动续行、勾选框点击即切换、表格按 Tab 在单元格间移动。配套设置：

{
  "markdown.extension.toc.omittedFromToc": {},
  "markdown.extension.list.indentationSize": "inherit",
  "markdown.editor.pasteUrlAsLink": "smart",
  "editor.quickSuggestions": { "strings": true }
}
​

列表缩进继承上层（嵌套列表不错位）、粘贴链接智能成引用格式、字符串内开补全（让片段包在文档里也生效）。这些小项每条只省一两秒，累积起来是"写作心流不断"的差别。

实时预览与大纲导航

预览用内置能力打底：侧栏并排预览，滚动同步（源码区滚动，预览跟随）。增强套件在此之上补齐快捷键级体验：预览内标题带大纲跳转、列表编辑自动化。写作时长文档的导航靠大纲视图（内置）加书签（2.3 节），三件配合覆盖"写到哪、跳回哪"的动线。

规范检查是第三条腿。文档也有"检查器"：检查器扩展对文档做风格诊断——标题层级跳跃、重复标题、行超长、尾随空格、列表风格混用，全部标出并可自动修复：

{
  "markdownlint.config": {
    "MD013": false,
    "MD033": false,
    "MD041": false,
    "MD025": { "front_matter_title": "" }
  }
}
​

这份禁用清单本身就要解释：行长度限制对中文文档意义有限（中文换行习惯不同）、内联超文本标记在技术文档里常见、首行标题规则对带前言的文档不适用——检查器服务规范，而不是规范服务检查器，配置该按文体调整，这与第 2 章"规则集按团队痛点微调"是同一个原则。

表格与图片：两件高频小装备

表格编辑器扩展：表格以结构化方式编辑（对齐、增删行列），不用数字符画格子；对维护大对照表（比如本册各节的装备清单）是刚需。图片粘贴装备：截图直接进剪贴板粘贴，自动落盘到资源目录、自动生成引用，文件名按时间或标题生成。文档配图的最后一道手工工序被抹平。

台面实测：一篇排查记录的诞生

拿工程师最常见的文档体裁实测：线上问题排查记录。动线：新建文档，敲标题，检查器提示标题后要空一行，顺手修复；正文列表自动续行，插入命令输出用代码块补全触发；贴日志截图，直接粘贴成引用；写结论时用勾选框列后续动作。全程预览侧栏开着，滚动同步确认排版；写完跑一次检查器的全部修复，格式规范一次达标。文档入库、评审、归档——它和代码走完全相同的流程，这正是"文档代码化"的工位含义。

坑点提醒

坑一，检查器与正文冲突。 长段中文行被行长度规则反复标警时别硬折行（中文折行破坏排版），调规则不折内容。坑二，图片目录漂移。 粘贴装备的落盘目录要在项目里固定，否则文档一搬家图全裂；目录进版本控制。坑三，预览插件重复。 增强套件自带预览增强，再装独立预览插件会双份渲染，按"一套主体加内置预览"的组合收敛。

常见疑问快答

问：中文技术文档，检查器的规则该怎么调？答：核心调整三处——行长度限制对中文意义有限可关（中文不按空格断行，硬折行破坏排版）；标题层级跳跃的规则保留（结构问题与语言无关）；首行标题规则按文档是否有前言灵活处理。原则始终是：检查器适配文体，不是文体迁就检查器。

问：文档也要“保存即格式化”吗？答：可以，但档位要轻——文档的格式化只做基础整理（列表标记统一、空行规范），激进的自动折行与重排会破坏手工排版意图。格式化器对文档类型通常有单独的配置段，把它调到“温和档”。

问：写长文档时大纲和书签怎么配合？答：大纲管“结构导航”（章节间跳），书签管“工作点标记”（正在改的几处来回跳），两者一个是地图一个是路标。写万字级文档时，再把待办标记埋进未完成段落，收尾时按待办树逐个清——这套组合是 2.3 节导航装备在文档场景的复用。

问：表格很宽时编辑体验很差，有解吗？答：宽表用表格编辑器的结构化编辑（单元格独立编辑，不受字符宽度折磨）；确实超宽的表考虑拆表或转成定义列表。表格的可读性边界大约在五列以内，超过就该反思信息组织而不是硬撑。

问：文档预览渲染和平台渲染不一致，以谁为准？答：以目标平台的渲染为准——编辑器预览是近似（扩展语法支持有差异）。发布前在平台侧过一眼是终检；频繁不一致的语法干脆少用，文档的可移植性比花哨重要。

问：写技术文档时，中英混排的空格规范要不要管？答：建议管但交给工具管——检查器与格式化器能处理混排间距的统一，人工维护既累又不稳。规范的意义在于一致，谁来执行不重要，能自动化的都自动化。

替代方案

文档的重型替代是专门的写作与发布工具链（适合长篇书稿或站点发布，本册的配图流水线就是那类工具链的分支）；轻量替代是纯文本编辑加渲染预览网站。编辑器内三位一体的定位是"与代码同仓的工程文档"——评审、版本、追踪都与代码一体。下一节从内容转向感官：主题与图标，工位的照明与铭牌。