Markdown 语法 · 排错

Markdown 不渲染？
常见的坑，以及每个怎么修

你的 Markdown 显示成了符号、而不是排版,你想知道为什么。几乎每种情况都归到两件事之一:

  • 你根本不在 Markdown 渲染器里,所以整个文件显示原始的 #、*、- 符号。
  • 某一处有小语法失误,而其余都渲染正常。

快速判断就看坏了多少。如果整个文件都是原始符号,是渲染器问题;如果大部分看着正常、只有一处不对,是语法失误。下面每种都讲,附修法。

先看：你到底在不在 Markdown 渲染器里

这是最常见的原因、也最容易忽略。Markdown 只有在工具渲染它时才会变成标题和加粗。用纯文本工具打开同一个文件,你看到的就是源码:那些字面符号。那不是文件坏了,只是没被渲染。

你在哪看 你看到的
记事本或纯文本编辑器 原始的 #、-、* 和代码围栏符号，原样
不带预览的聊天或表单框 源码文本，不是渲染后的结果
只渲染部分 Markdown 的工具 大部分排版了，但少数还留成符号

修法:用一个能渲染 Markdown 的东西打开文件。怎么做看 md 文件怎么打开。

然后：单点的语法坑

如果大部分页面渲染了、只有一处不对,那是语法失误。在下面找到你的症状、照修法走。

你看到的 大概的原因 修法
**文字** 显示星号、而不是加粗 纯文本视图，或标记里有空格 Markdown 粗体不生效
按回车不另起新行 需要两个行尾空格、一个空行，或换行标签 Markdown 换行
--- 变成了大标题，或没出现分隔线 Setext 坑，或 --- 前后缺空行 Markdown 分隔线
图片空白或坏了 路径写错，或工具读不到你的本地文件 Markdown 图片不显示
图片渲染了但太大 标准 Markdown 没有尺寸语法，得设个宽度 Markdown 图片尺寸
表格显示成原始的竖线和横线 表头分隔行缺失或写错 Markdown 表格
代码块的围栏符号显示成文本 围栏没闭合，或信息行写错 Markdown 代码块
想字面显示的符号被当成了排版 需要转义它 Markdown 转义

如果这些符号本身你还不熟,Markdown 怎么写 是起点。

两个根因，一句话

几乎每个"我的 Markdown 不渲染"的情况,要么是一个不渲染 Markdown 的查看器(整个都是原始的),要么是一处小语法失误(只有一处不对)。先分清是哪种,修法就跟着来了。

在 NoteLoom 里看它当场渲染

诊断这两种问题最快的办法,就是看文件渲染。NoteLoom 是个在浏览器里读写本地 .md 文件的编辑器:它的 live 和 reading 视图边打边渲染你的 Markdown,你能看出具体哪一行没渲染、当场修。而如果一个文件在别处看着是原始符号,在这里打开就知道一直是渲染器问题。

NoteLoom 遵循 CommonMark,所以你看到的和多数 Markdown 工具的行为一致。先说清边界:它没有任何 AI,只是把你本地的 Markdown 渲染出来、存回去。

用起来:用 Chrome / Edge / Arc 打开 app.noteloom.cc,挂载一个本地文件夹,在 source 视图里写、看 live 视图渲染出的页面。直接存回本地,不上云、不用账号。

相关阅读

md 文件怎么打开？ 那个大修法：把文字放进真正渲染 Markdown 的工具。 Markdown 粗体不生效？ 看到 ** 而不是加粗时。 换行为什么不生效？ 按回车不另起新行时。 Markdown 分隔线（以及 --- 的坑） --- 变成标题而不是分隔线时。 Markdown 怎么写？ 基础语法，如果你刚起步。

FAQ

我的 Markdown 为什么不渲染？
几乎都是两件事之一。要么你在一个不渲染 Markdown 的工具里看，整个文件显示原始的 # 和 * 和 - 符号；要么大部分渲染了、只有一处有小语法失误。快速判断：是整个文件都是原始的，还是只有一部分？
为什么我的 Markdown 把 # 和 * 显示成符号？
因为它没被渲染。记事本这类纯文本编辑器显示的是 Markdown 源码、不是排版结果。用 Markdown 编辑器或查看器打开，同样的符号就会变成标题、加粗和列表。
我的 Markdown 在一个 app 渲染、另一个不渲染，为什么？
第二个 app 不渲染 Markdown，或只渲染一部分。你的文字没问题，是工具的限制。任何把原始符号显示出来的东西，就是没在渲染 Markdown。
怎么区分是渲染器问题还是语法问题？
看坏了多少。如果整个文件都是原始符号，是渲染器问题：用一个 Markdown 工具打开它。如果大部分渲染了、只有一处（一个加粗、一张图、一个表格）不对，是语法失误，对应的修法页会讲每一种。
NoteLoom 能帮我看出哪里没渲染吗？
能。NoteLoom 的 live 和 reading 视图边打边渲染你的 .md，而且遵循 CommonMark，所以你能看出具体哪一行没渲染、当场修。如果一个文件在别处显示成原始符号，在 NoteLoom 里打开就知道原来一直是渲染器问题。它没有任何 AI，只渲染和存回你本地的 Markdown。
手机或 Safari 能用 NoteLoom 弄吗？
目前不行。NoteLoom 依赖浏览器的 File System Access API，当前支持 Chrome、Edge、Arc 这类 Chromium 系桌面浏览器；Firefox、Safari 和手机端暂不支持。

看着你的 Markdown 渲染、找出哪里不对

用 Chrome / Edge / Arc 打开 NoteLoom,挂载一个本地文件夹,在 source 视图里写、live 视图当场渲染,你就能看出具体哪一行没渲染。直接存回本地,不用装软件,也不用注册账号。

打开 NoteLoom 试试