编辑指南

如何清理转换后的 Markdown

转换后的 Markdown 是由另一种格式中的结构线索拼装而成的草稿。分轮进行:先去除提取噪音、修复大纲、规范化块级语法、核验引用,最后再润色文字。

阅读时间约 10 分钟

编辑前保留原始转换结果

把转换结果保留为独立的文档,并在评审完成前保留源文件。这样当文本看似缺失或顺序错乱时,你就有参照,也能防止无关的未保存草稿被覆盖。

在执行自动化清理操作后使用撤销,并且每次只做一类修改。大范围的改写可能意外删除代码中有意的空格,或改变原本正确的列表嵌套。

去除提取噪音

PDF 页眉、页码、重复的页脚、幻灯片标签、空表格行和重复的空行往往毫无意义。搜索重复的片段并统一删除,注意不要删掉同时属于真实内容的短语。

  • 把代码块之外连续三个及以上的空行压缩为一个。
  • 把仅因 PDF 行尾连字符而断开的单词重新拼接。
  • 删除每页重复的导航或法律套话。
  • 移除空标题和空列表项。

重建合乎逻辑的标题大纲

用一个 H1 作为文档标题。主要章节一般用 H2,子章节用 H3,依此类推。不要仅仅为了得到更小的视觉样式而跳级;呈现效果属于渲染器的职责。

转换后的 PDF 可能过于激进地把加粗行标为标题,而手动格式化的 Word 文档可能根本不会标记。把大纲当作目录来读,并根据含义调整标题级别。

修改前后Markdown
Before:
# Deployment
#### Prerequisites
## Linux

After:
# Deployment
## Prerequisites
### Linux

规范化列表和间距

无序列表项使用统一的标记符号,嵌套使用一致的缩进。列表前后各保留一个空行,但除非每个短条目都包含多个段落,否则不要在条目之间添加空行。

转换器可能把编号标题或表格单元格误当成列表项。请确认有序编号承载的是含义,而不是反映源页面上的标签。

简化表格,以适应窄屏和源文本可读性

检查每一行是否拥有相同数量的单元格,以及内容中的竖线字符是否已转义。精简冗长的表头、把长说明移到表格下方,并拆分无关的列组。

合并单元格、嵌套表格、图表和电子表格公式在 Markdown 表格中没有可靠的对应物。请用列表、几个小表格、文字摘要或指向持续维护的源数据的链接来替代。

核验链接、图片和代码

从 HTML 或 EPUB 继承而来的相对链接依赖其原始位置。PDF 提取可能拆分 URL,Office 文档可能包含目标已改变的显示文本。请在最终目标环境中逐个打开重要链接。

为保留的图片添加描述性的替代文本。确认围栏代码使用了正确的语言,且特殊字符没有被排版工具转换。除非已把复制的命令当作不可信内容进行评审,否则切勿执行。

以含义收尾,而不是外观

把名称、日期、数量、代码和决策与源文件逐一比对。改写那些依赖页面位置、幻灯片视觉效果或电子表格颜色的句子。然后在桌面和窄屏宽度下预览、下载 .md 文件,并在发布系统中验证。

一次干净的转换读起来应该像一份直接用 Markdown 写成的文档——即使原件仍然是权威记录。

在一个工作区里清理下一次转换

打开转换后的草稿、对比源文本和预览,然后复制或下载经过评审的 Markdown。

转换受支持的文件