文档与 OCR实用指南

Markdown 预览排版错乱?检查标题、列表缩进与代码围栏

Markdown 看起来只是文本,但一个空格或未闭合的代码围栏就能改变整段文档的结构。排版问题应先定位源文件中的语法,再检查目标平台的渲染规则。这篇用一份完整短笔记走通源码、预览和交付检查,避免在截图里反复修补表面样式。

代码编辑器中的分层文本与程序源代码
配图:Juanjo Jaramillo · Unsplash License

先把问题解决

先用最小样例确认标题、列表和围栏代码块能被正确识别,再逐段恢复内容。本站预览把渲染的 HTML 放在无脚本权限的 iframe 中;它不是网页发布、PDF 导出或跨平台排版一致性的保证。

为什么先查结构,再改视觉样式

CommonMark 0.31.2 规范定义了标题、列表和围栏代码块等基础语法。不同平台还可能有扩展和自己的样式,因此“此处看起来正确”与“目标平台同样显示”要分开验收。本站使用 Markdown 解析器生成 HTML,并在隔离预览中展示。

先保存原始文本,再修一处、预览一次。若是整理带引用的学习资料,保留章节、页码和版本定位;换成 Markdown 不能丢掉证据出处。

一份包含三种结构的完整样例

下面是本站自编笔记,不是外部研究的摘要。它包含一级与二级标题、两条项目和一个字面代码块;编号 0012 放在引号里,只表示示例文本。复制时把开头到结尾一起保留,不删除闭合围栏。

  1. 打开Markdown 预览,将样例粘贴到原始文本区域,开始处理。
  2. 确认 Review notes 是一级标题,Evidence 是二级标题,两条项目是一个列表,而不是带破折号的普通段落。
  3. 确认 item_id 和 status 留在代码块里,0012 未被删零,末尾参考链接位于代码块外。
  4. 修复真实文档时先换掉一个章节,保留空行和围栏成对关系,逐段扩展到全文。修改输入后需要重新处理,旧预览不能证明新输入已检查。

复制到预览工具的原始 Markdown

# Review notes

## Evidence

- Keep the source locator.
- Check the exported document.

```text
item_id: "0012"
status: pending
```

[CommonMark specification](https://spec.commonmark.org/0.31.2/)
样例保留英文文本,便于核对符号、空行与原样代码;内容不是需要执行的命令。

从错误形态回到具体字符

常见症状与源码检查点
症状先检查修复后的观察
后半篇都变成代码开围栏是否缺少闭合围栏后续段落重新回到普通文本
标题仍显示 #标记后是否有空格,是否仍在代码块内成为对应层级标题
项目内容被识别为代码缩进是否无意形成代码结构列表层级与文字归属正确
链接也变成字面文本是否被包在代码围栏中代码外的链接正常识别

不确定时先去掉复杂嵌套,保留一个项目与一段续写;确认后再恢复多层列表,避免同时改多个变量。

源码、HTML 与最终平台是三个交付对象

预览页的结果复制会复制渲染后的 HTML,而不是重新生成一份 Markdown 源文件。需要继续编辑 Markdown 时,应保存左侧原始文本;需要 HTML 时才复制结果,并在目标平台重新核对。本站没有在此入口提供网页托管或 PDF 发布。

代码块用于保留示例的字面文本,不证明 JSON、公式或命令有效。若内容涉及 CSV 与 JSON 的互转,再按引号、换行和编号检查验算数据本身。语法高亮或排版整齐不能替代格式验证。

按交付用途保存

继续写作

保留原始 Markdown、资料来源与版本。

发布到平台

在目标编辑器核对其扩展、链接与图片规则。

提供代码示例

保留字面文本,再用对应解析器或测试核验。

沙盒不会让外部图片变成本地资料

本站 iframe 的 sandbox 为空,不允许脚本执行。它仍可能请求文档引用的外部图片;预览不等于离线,也不意味着外部服务看不到图片请求。首次检查可使用不含图片的样例,敏感资料按组织规则处理。

原始 HTML、外链、扩展表格与目标平台可能有不同处理方式。不要用陌生 HTML 测试日常排版问题,也不要假设本站预览允许的结构都会被发布平台保留。文章内容的可靠性、链接许可与图像出处需要另外核对。

把“好看”改成可核对的验收条件

交付前逐项检查

  • 标题层级与章节意图一致,没有围栏吞掉后文。
  • 列表归属、代码原文与编号完整。
  • 引用链接有来源定位,图片访问边界已明确。
  • 源文件已保存,并在最终平台复查整篇。

常见问题

一行换行为什么没有变成新段落?

普通换行不必然建立独立段落。先按目标语法使用空行分段;需要强制换行时核对平台规则,不用大量空格修视觉位置。

为什么复制结果得到 HTML?

该入口把 Markdown 渲染为 HTML,结果复制使用渲染输出。继续编辑时保存原始 Markdown;交付 HTML 时在目标平台复核。

能直接发布成网页或 PDF 吗?

这个入口提供沙盒预览,没有执行网页托管或 PDF 导出。发布或打印属于后续步骤,需要另行检查完整正文、链接和分页。

参考资料与延伸阅读

按步骤开始处理

进入对应工具,预览处理结果,检查导出的文件。

这个主题的后续文章

沿着同一主题,继续阅读引用了本文的新文章。

继续阅读