Markdown Syntax · Troubleshooting

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

If you are still learning the symbols in the first place, how to write Markdown is the place to start.

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: its live and reading views 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. To be clear about the boundaries: it has no AI, it just renders and saves your local Markdown.

How you use it: open app.noteloom.cc in Chrome / Edge / Arc, mount a local folder, and write in the source view while the live view shows the rendered page. Saved straight to your disk, no cloud, no account.

Related reading

How do you open a .md file? The big fix: open your text in a tool that actually renders Markdown. Markdown bold not working? When ** shows instead of bold. Why aren't your line breaks working? When pressing Enter does not start a new line. Markdown horizontal line (and the --- trap) When --- turns into a heading instead of a divider. How to Write Markdown? The basic syntax, if you are just getting started.

FAQ

Why is my Markdown not rendering?
It is almost always one of two things. Either you are viewing the file in a tool that does not render Markdown, so the whole thing shows raw # and * and - symbols, or most of it renders and just one piece has a small syntax slip. The quick test: is the WHOLE file raw, or only one part?
Why does my Markdown show # and * as plain symbols?
Because it is not being rendered. A plain text editor like Notepad shows the Markdown source, not the formatted result. Open the file in a Markdown editor or viewer and the same symbols turn into headings, bold, and lists.
My Markdown renders in one app but not another. Why?
The second app does not render Markdown, or renders only part of it. Your text is fine; the tool is the limit. Anything that shows the raw symbols simply is not a Markdown renderer.
How do I tell a renderer problem from a syntax problem?
Look at how much is broken. If the WHOLE file shows raw symbols, it is a renderer problem: open it in a Markdown tool. If most of it renders and only one thing is off, a bold, an image, a table, it is a syntax slip, and the specific fix pages cover each one.
Can NoteLoom help me see what is not rendering?
Yes. NoteLoom renders your .md as you type in its live and reading views, and it follows CommonMark, so you can see exactly which line is not rendering and fix it on the spot. And if the whole file shows raw symbols elsewhere, opening it in NoteLoom shows you it was a renderer problem all along. It has no AI; it just renders and saves your local Markdown.
Can I do this with NoteLoom on my phone or in Safari?
Not for now. NoteLoom relies on the browser’s File System Access API, which currently works in Chromium-based desktop browsers like Chrome, Edge, and Arc. Firefox, Safari, and mobile are not supported yet.

Watch your Markdown render, and spot what is off

Open NoteLoom in Chrome / Edge / Arc, mount a local folder, and write in the source view while the live view renders it, so you can see exactly which line is not rendering. Saved straight back to your disk, no software to install and no account to sign up for.

Open NoteLoom and try it