Markdown Not Rendering? Work Through It in This Order

Before changing anything, look at how much is broken. This single observation splits every case into one of two families and saves you from editing syntax that was never wrong.

If the **entire document** is raw — every # visible, every asterisk showing, nothing formatted anywhere — the problem is not your Markdown. You are looking at it in something that does not render Markdown at all, or the file is not being treated as Markdown. Skip straight to the viewer and file-name checks below.

If **most of it renders but one thing is broken** — a table that stayed as pipes, a list that refused to nest, a bold phrase still wrapped in asterisks — then the renderer is working fine and you have a syntax slip in that one element. Jump to the spacing and indentation sections.

A quick way to settle which it is: paste the document into a known-good renderer and see what happens. If it renders correctly in the viewer here but not where you were working, the file is fine and the environment is the problem.

This is the most common cause by a wide margin, and the most commonly overlooked, because the file looks right — it is the viewer that is not participating. Notepad, TextEdit, most email clients, Word, plain text fields, terminal output and many CMS boxes all display Markdown literally. They are not broken; they simply have no Markdown parser, so every character you typed is shown as a character.

The same file that looks like a mess in one place renders perfectly in another. Opening a .md file in a code editor without turning on preview has the same effect: VS Code shows you the source until you explicitly open the preview pane, which catches people out constantly because the editor clearly *knows* it is Markdown and still shows raw text by default.

The fix is to open it somewhere that renders. If you want to check a file quickly without installing anything, drop it into the online Markdown viewer and you will see the rendered result immediately. If the destination genuinely cannot render Markdown — Word being the usual case — then conversion rather than viewing is what you need, and the Markdown to Word converter will give you real formatting instead of symbols.

Pasting an AI answer into Word is the single most common version of this, common enough that it has its own walkthrough — including the reason Word recognises *bold* while you type but never when you paste.

Platforms decide whether to render based on the file name, not the contents. A file saved as notes.txt holds exactly the same characters as notes.md and will still be shown as plain text, because nothing told the platform to run a Markdown parser over it — the extension is a signal to software, not a different kind of data. Check the real extension rather than what the file icon suggests — Windows hides known extensions by default, so a file displayed as "notes.md" can actually be "notes.md.txt" on disk.

For a repository README specifically, the file must be named README.md, and on case-sensitive filesystems the capitalisation matters. Encoding is the other quiet culprit: save as UTF-8. A file saved as UTF-16, or carrying a byte-order mark, can render as garbled characters or refuse to parse the first line, which is especially confusing when that first line is your title heading.

More broken Markdown comes down to blank lines than to any actual syntax error. Markdown uses blank lines to decide where one block ends and the next begins, so a heading, list or table that is jammed directly against the paragraph above it may be absorbed into that paragraph instead of starting a new block.

The classic version of this: a line of text with three dashes directly underneath. You meant a divider, but in CommonMark a line of dashes immediately below text is Setext syntax for a heading, so your paragraph silently becomes a large heading and the divider never appears. Leaving a blank line between them fixes both.

The rule to internalise is simply that block-level elements want breathing room. When something will not start, add a blank line above it before you start doubting the syntax.

Nested lists are where otherwise valid Markdown most often falls apart, because implementations disagree about how much indentation creates a child item. CommonMark aligns a nested item with the start of its parent content, which typically means two spaces for a bullet list, while a number of older parsers expect four spaces or a tab.

Mixing tabs and spaces in the same list is what produces genuinely unpredictable output — items flattening to one level, or a sub-item silently becoming a code block because the editor turned a tab into enough whitespace to trigger an indented code block. Choose spaces, keep the amount consistent, and let your editor show whitespace if a list is misbehaving for no visible reason.

Ordered lists hide a related surprise: the numbers you type are mostly ignored. A list written 1. 1. 1. still renders 1, 2, 3, because the renderer counts items itself and only reads the first number to decide where to start. If your numbering looks wrong in the output, the cause is usually a break in the list — a missing indent or stray blank line — rather than the digits themselves.

Tables are not part of original Markdown — they come from GitHub-Flavored Markdown (GFM), so a table that renders on GitHub can stay as raw pipes somewhere running a stricter CommonMark parser. When a table does not render in a GFM-capable viewer, the separator row is nearly always the reason: the second row must consist of dashes, with at least three per column, and the column count has to match the header exactly.

Code fences fail in a different way, and the symptom is distinctive — everything after the block loses its formatting. That happens when an opening triple-backtick fence is never closed, so the renderer treats the entire remainder of the document as code. If your page renders normally and then abruptly turns into one long code block, search for an unbalanced fence rather than inspecting the elements below it.

A subtler case: to show triple backticks inside a code block, the outer fence needs more backticks than the inner one — four outside, three inside. Using three for both closes the block early, which produces exactly the half-rendered mess the previous paragraph describes.

Markdown allows inline HTML, which leads people to reach for a <div>, a <style> block or an <iframe> when Markdown alone will not do what they want — and then to find it missing from the output with no error anywhere.

It was almost certainly sanitized. Any platform that renders Markdown written by other people has to filter the resulting HTML, or it would be handing out an easy path to script injection. Sanitizers work from an allowlist: a set of tags and attributes known to be safe is kept, and everything else is silently dropped. This is why simple presentational tags survive while scripts, styles, iframes and most event-handler attributes vanish.

Silently is the operative word — you get no warning, just absent content, which is why this one is so hard to diagnose from the symptom alone. If a tag disappeared on a hosted platform and works in your local preview, assume the allowlist and find a Markdown-native way to express it rather than escalating to more HTML.

The last category is not a failure at all. There is no single Markdown — CommonMark is the strict core, GFM layers tables, task lists, strikethrough and autolinking on top, and individual tools add their own extensions such as footnotes, callouts or math. A document can be completely valid and still render three different ways in three places.

Task lists are the usual example: - [x] renders as a checked box on GitHub and as literal brackets in a plain CommonMark renderer. Footnotes, callout blocks and LaTeX math are all extensions too, supported in some tools and invisible in others. The practical move is to write to the lowest common denominator your audience will actually use — CommonMark plus GFM covers nearly everything — and check the output where it will be read rather than only where you wrote it.

If you want a reference for what the core syntax does, the Markdown syntax guide shows every element with a live rendered example beside it. And when the destination is a document rather than a web page, converting is more reliable than hoping the target supports your flavour: Markdown to Word and Markdown to PDF both preserve tables and code blocks that a mismatched renderer would flatten.