START WITH THE SYMPTOM

Markdown looks wrong.
Find out why.

A formatting problem can come from your source, a renderer setting, or a missing file. Choose the symptom below and work through a small, reproducible example.

A useful diagnostic sequence

01Reduce the source
02Check renderer support
03Verify the destination

Fix one variable at a time. A working preview does not prove every publishing destination supports the same extensions.

TROUBLESHOOTING

Text runs together

Separate a soft break, hard break and new paragraph.

TROUBLESHOOTING

Images are missing

Resolve the asset path and check whether the URL is public.

TROUBLESHOOTING

Links open the wrong page

Check the current document folder, final URL and heading fragment.

TROUBLESHOOTING

Nested lists fall apart

Check parent marker width and continuation indentation.

TROUBLESHOOTING

Code loses formatting or color

Distinguish an unclosed fence from an unavailable language grammar.

TROUBLESHOOTING

Tables display as pipes

Check the delimiter row and whether GFM tables are enabled.

TROUBLESHOOTING

Diagrams appear as code

Check the mermaid fence and support in the destination renderer.

TROUBLESHOOTING

Equations display as source

Check delimiters and the destination math engine.

What a preview can and cannot tell you

A live preview helps you isolate changes. It cannot make a private image public or add Mermaid support to another website. Save the editable source and verify the delivered page or export. For a broad syntax reference, use the Markdown guide.

These troubleshooting guides use primary syntax documentation. See CommonMark and the GFM specification. This page organizes existing solutions rather than promising compatibility with every renderer.

Before reporting a renderer bug

What a preview can and cannot tell you