Markdown 语法 · 排错

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

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

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

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

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

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

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

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

然后：单点的语法坑

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

你看到的 大概的原因 修法
**文字** 显示星号、而不是加粗 纯文本视图，或标记里有空格 Markdown 粗体不生效
按回车不另起新行 需要两个行尾空格、一个空行，或换行标签 Markdown 换行
--- 变成了大标题，或没出现分隔线 Setext 坑，或 --- 前后缺空行 Markdown 分隔线
图片空白或坏了 路径写错，或工具读不到你的本地文件 Markdown 图片不显示
图片渲染了但太大 标准 Markdown 没有尺寸语法，得设个宽度 Markdown 图片尺寸
表格显示成原始的竖线和横线 表头分隔行缺失或写错 Markdown 表格
代码块的围栏符号显示成文本 围栏没闭合，或信息行写错 Markdown 代码块
想字面显示的符号被当成了排版 需要转义它 Markdown 转义
复选框显示成 [ ] 文本，或方框点不动 工具不渲染 GFM 任务列表，或方括号里少了空格 Markdown 复选框
callout 显示成原始的 [!NOTE] 引用、不是彩色卡片 工具不渲染 callout（Obsidian 风扩展） Markdown 提示框
公式把美元符号和 LaTeX 显示成纯文本 工具不支持数学，或美元符号内侧有空格 Markdown 数学公式
脚注显示成原始 [^1] 文本，或点了不跳 工具不支持脚注，或引用没有配套的定义 Markdown 脚注
:smile: 这种短代码一直是一串字 emoji 短代码是平台功能，CommonMark/GFM 里没有 Markdown 打 emoji
文件开头有块 --- 包着的内容，显示成表格或原文 那是 YAML frontmatter，元数据，各查看器处理不一 frontmatter 是什么
[TOC] 显示成字面的 [TOC] 文字 TOC 是平台功能，不是标准 Markdown 语法 Markdown 目录

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

两个根因，一句话

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

在 NoteLoom 里看它当场渲染

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

NoteLoom 遵循 CommonMark，所以你看到的和多数 Markdown 工具的行为一致。它只是把你本地的 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 里打开就知道原来一直是渲染器问题。它只渲染和存回你本地的 Markdown。
手机或 Safari 能用 NoteLoom 弄吗？
目前不行。NoteLoom 依赖浏览器的 File System Access API，当前支持 Chrome、Edge、Arc 这类 Chromium 系桌面浏览器；Firefox、Safari 和手机端暂不支持。

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

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

打开 NoteLoom 试试

作者：哔噗，NoteLoom 的独立开发者。文中关于产品的说法，都对照过应用的真实行为。