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 怎么写 是起点。
Codex 对话里出现「Markdown couldn't render」？
「Markdown couldn't render」加一个「Try again」按钮，是 OpenAI 的 Codex 应用和 VS Code 里的 Codex 扩展显示的报错框。看到它，不代表你没在 Markdown 渲染器里：这里负责渲染的就是 Codex。这个框占的是对话里某一条 Codex 消息的位置，可能是回复，也可能是进度更新。openai/codex #25913 附的截图里，框前后的消息照常显示。
出错那条消息的内容本身有没有问题，两份报告都没下结论。一位报告人写明，出错那条回复里的 Markdown 看上去是正常的；另一位希望至少能看到没渲染出来的原文，好判断内容哪里有问题。
GitHub 上有两份还没关闭的报告，写了这个报错在什么情况下出现：
- openai/codex #25913：macOS 上的 Codex 应用，版本 26.527.60818。报告人说每次用 Jira 的 MCP 都会刷出这个报错；给的复现步骤是装一个 Jira MCP，再写一个 Skill，让 Codex 在调用工具前后的进度更新里，把参数和返回结果按 JSON 打出来。
- openai/codex #38924：VS Code 里的 Codex 扩展，版本 26.810.52044，通过 Remote-SSH 连 Ubuntu 使用。一直报错的是一个跑过很多长任务、重连或重载 VS Code 后接着用的对话，会话文件约 28.7 MB，主机上同时有两个 Codex app-server 进程。点「Try again」、重载窗口都不一定管用；报告人说在新开的短对话里还没复现过。
截至 2026 年 9 月 14 日，两份报告都还开着，底下只有机器人留的查重评论。碰上这个报错，可以把自己的 Codex 版本号和系统补进对应的 issue。如果那一轮 Codex 正在改项目里的 .md 文件，直接打开文件本身，看看写进去的是什么。
两个根因，一句话
几乎每个"我的 Markdown 不渲染"的情况，要么是一个不渲染 Markdown 的查看器（整个都是原始的），要么是一处小语法失误（只有一处不对）。先分清是哪种，修法就跟着来了。
在 NoteLoom 里看它当场渲染
诊断这两种问题最快的办法，就是看文件渲染。NoteLoom 是个在浏览器里读写本地 .md 文件的编辑器：它的编辑模式和阅读视图边打边渲染你的 Markdown，你能看出具体哪一行没渲染、当场修。而如果一个文件在别处看着是原始符号，在这里打开就知道一直是渲染器问题。
NoteLoom 遵循 CommonMark，所以你看到的和多数 Markdown 工具的行为一致。你改的是磁盘上那个真正的 .md 文件，不是副本。
使用很简单：用 Chrome / Edge / Arc 打开 app.noteloom.cc，挂载一个本地文件夹，在源码模式里写、看编辑模式渲染出的页面。直接存回本地，不上云、无需账号。
FAQ
我的 Markdown 为什么不渲染？
为什么我的 Markdown 把 # 和 * 显示成符号？
我的 Markdown 在一个 app 渲染、另一个不渲染，为什么？
怎么区分是渲染器问题还是语法问题？
NoteLoom 能帮我看出哪里没渲染吗？
NoteLoom 在哪些浏览器里能用？
一秒定位 Markdown 渲染失败原因，实时修复
把排版错乱的 .md 文件放进本地文件夹，用 NoteLoom 边看源码边查对渲染，快速修正缺失空格或语法冲突，修改即刻存回原文件。
发布于 · 更新于