Markdown Not Rendering?
The common gotchas, and how to fix each
Your Markdown is showing up wrong, symbols instead of formatting, and you want to know why. Almost every case comes down to one of two things:
- You are not in a Markdown renderer at all, so the whole file shows its raw
#,*, and-symbols. - One specific piece has a small syntax slip, while everything else renders fine.
The quick test is how much is broken. If the whole file is raw symbols, it is a renderer problem. If most of it looks right and only one thing is off, it is a syntax slip. Here is each, with the fix.
First: are you even in a Markdown renderer?
This is the most common cause by far, and the easiest to miss. Markdown only turns into headings and bold when a tool renders it. Open the same file in a plain text tool and you see the source: the literal symbols. That is not a broken file, just an unrendered one.
| Where you are looking | What you see |
|---|---|
| Notepad or a plain text editor | The raw #, -, *, and code-fence symbols, exactly as typed |
| A chat or form box with no preview | The source text, not the formatted result |
| A tool that renders only part of Markdown | Most of it formatted, but a few things left as symbols |
The fix: open the file in something that renders Markdown. See how to open a .md file for the ways to do that.
Then: the single-thing syntax gotchas
If most of the page renders and only one thing is off, it is a syntax slip. Find your symptom below and follow the fix.
| What you see | Likely cause | Fix |
|---|---|---|
| Your **text** shows the asterisks instead of bold | A plain-text view, or a space inside the markers | Markdown bold not working |
| Pressing Enter does not start a new line | Markdown needs two trailing spaces, a blank line, or a break tag | Markdown line breaks |
| Your --- became a big heading, or no divider appears | The Setext trap, or missing blank lines around the --- | Markdown horizontal line |
| An image is blank or broken | A wrong path, or a tool that cannot reach your local file | Markdown image not showing |
| An image renders but is far too big | Standard Markdown has no size syntax, so you set a width | Markdown image size |
| A table shows as raw pipes and dashes | The header separator row is missing or malformed | Markdown tables |
| A code block shows its fence marks as text | The fence is not closed, or the info line is off | Markdown code blocks |
| A symbol you wanted literally got turned into formatting | You need to escape it | Escaping characters in Markdown |
| A checkbox shows as [ ] text, or the box will not tick | The tool does not render GFM task lists, or a space is missing in the brackets | Markdown checkboxes |
| A callout shows as a raw [!NOTE] quote, not a colored box | The tool does not render callouts, an Obsidian-flavored extension | Markdown callouts |
| A formula shows the dollar signs and LaTeX as plain text | The tool has no math support, or a space is just inside the dollar signs | Math in Markdown |
| A footnote shows as raw [^1] text, or does not link | The tool does not support footnotes, or a reference has no matching definition | Markdown footnotes |
| A :smile: shortcode stays as colon-and-name text | Emoji shortcodes are a platform feature, not CommonMark or GFM | Emoji in Markdown |
| A --- block at the very top shows as a table or raw text | That is YAML frontmatter, metadata that viewers treat differently | What is frontmatter? |
| A [TOC] marker shows as the literal text [TOC] | TOC is a platform feature, not standard Markdown syntax | Markdown table of contents |
If you are still learning the symbols in the first place, how to write Markdown is the place to start.
Seeing "Markdown couldn't render" in Codex?
"Markdown couldn't render" with a Try again button is an error box in OpenAI's Codex app and in the Codex extension for VS Code. Seeing it does not mean you are outside a Markdown renderer, because Codex is the renderer here. The box takes the place of a single Codex message in the chat, such as a reply or a progress update. In the screenshot attached to openai/codex issue #25913, the messages around the box still render normally.
Neither report settles whether the text of the failed message is at fault. One reporter said the Markdown in the failed reply looked valid. The other asked for a way to see the text Codex failed to render, so they could find the problem in it.
Two open reports on GitHub describe when the error appears. In openai/codex #25913 (Codex app 26.527.60818 on macOS), it appeared every time the reporter used a Jira MCP server. The reproduction steps add a skill that tells Codex to print each tool call's JSON payload and result in its progress updates.
In openai/codex #38924 (Codex extension 26.810.52044 in VS Code over Remote-SSH), the error kept appearing in a long-running conversation that had been resumed after reconnecting or reloading VS Code. The session file was about 28.7 MB, and two Codex app-server processes were running on the host. Clicking Try again or reloading the window did not reliably clear it. The reporter has not reproduced it in a new, short conversation.
As of September 14, 2026, both issues are still open, and the only comment on either is an automated duplicate check. If you hit the error, add your Codex version and platform to the matching issue. If that turn was editing a .md file in your project, open the file itself to see what was written.
The two root causes, in one line
Almost every "my Markdown is not rendering" case is either a viewer that does not render Markdown (the whole thing is raw) or a small syntax slip (one thing is off). Sort out which first, and the fix follows.
See what is rendering, live, in NoteLoom
The fastest way to diagnose either problem is to watch the file render. NoteLoom is an editor that reads and writes local .md files in the browser: Edit mode and Reading view render your Markdown as you type, so you can see exactly which line is not rendering and fix it. And if a file looked like raw symbols somewhere else, opening it here shows it was a renderer problem all along.
NoteLoom follows CommonMark, so what you see matches how most Markdown tools behave. You are editing the real .md file on your disk, not a copy.
How you use it: open app.noteloom.cc in Chrome / Edge / Arc, mount a local folder, and write in Source mode while Edit mode shows the rendered page. Saved straight to your disk, no cloud, no account.
FAQ
Why is my Markdown not rendering?
Why does my Markdown show # and * as plain symbols?
My Markdown renders in one app but not another. Why?
How do I tell a renderer problem from a syntax problem?
Can NoteLoom help me see what is not rendering?
Which browsers can I use NoteLoom in?
Troubleshoot and Fix Broken Markdown Rendering Live
Mount your troublesome file in NoteLoom via Chrome or Edge. Toggle between Source and Reading views to spot syntax errors and fix them in place immediately.
Fix Markdown Rendering in Browser →Published · Updated