Recommended Free Tools
Markdown is source text interpreted by a parser, so what looks obvious in an editor may not be what the destination displays. The renderer’s rules—and the Markdown dialect it supports—determine whether a line becomes a paragraph, heading, list item, code block or hard line break. To debug a surprise, preview in the destination and inspect the source just before the first point where the output differs.
Why does my Markdown look different when rendered?
Markdown is plain-text markup: its symbols and layout are instructions for a processor, not formatting that the text carries on its own. A renderer parses those instructions and produces formatted output, commonly HTML. That means source appearance alone cannot guarantee the result. The Markdown syntax reference describes the relationship between Markdown text and rendered HTML.
| # | Preview | Product | Price | |
|---|---|---|---|---|
| 1 |
|
The Markdown Guide | $7.95 | Buy on Amazon |
| 2 |
|
Markdown: A Complete Guide | $9.99 | Buy on Amazon |
| 3 |
|
Using Markdown: A Short Instruction Guide | $9.99 | Buy on Amazon |
| 4 |
|
Learn Markdown: The Complete Guide on Markdown Formatting | $0.99 | Buy on Amazon |
| 5 |
|
Guide to Markdown Mode for Emacs | $9.99 | Buy on Amazon |
As an Amazon Associate I earn from qualifying purchases.
There is also more than one set of parsing rules. CommonMark formalizes core Markdown behavior; GitHub Flavored Markdown (GFM) is based on CommonMark and adds features used on GitHub, including tables, task lists and autolinking. An extension that works in one editor may be treated as plain text—or differently parsed—in another. Check the destination’s dialect before relying on a feature.
The CommonMark project notes that the original syntax left decisions open, including how to parse list indentation, line breaks and HTML blocks. Its specification says it is written “from the point of view of the human writer, not the computer reader.” The aim is to make ordinary documents render as writers intend while giving processors predictable rules. Read the CommonMark project documentation.
#1 Best Overall
Renderer differences can matter even when the source does not change. In a 2017 account of GitHub’s move to a CommonMark-based implementation, GitHub estimated that less than 1% of its existing user content would be affected. That was a historical estimate based on rendering content with its older Sundown parser and the new cmark implementation, normalizing the HTML and comparing the resulting trees. It is not a general error rate for Markdown files or other platforms. GitHub Engineering explains the migration analysis.
Why is my Markdown list formatting wrong?
Lists are parsed from markers, whitespace and surrounding blocks, not merely from lines that look alike. CommonMark treats a change in bullet character as the start of a new list; changing an ordered-list marker from a period to a closing parenthesis also starts a new list. The number on the first ordered-list item can affect the list’s starting number. Keep markers consistent when you intend one continuous list, and check indentation on continuation lines.
Rank #2
Indentation can change a line’s meaning. In GFM’s examples, four leading spaces can turn text into an indented code block rather than a heading or paragraph. Within a list, continuation text must be indented appropriately relative to the list marker. If a list unexpectedly breaks or becomes code, inspect the whitespace at the beginning of the affected lines. The GFM specification provides formal examples of list and block parsing.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Why do dashes turn into a heading or horizontal rule?
A line of hyphens has no single meaning in isolation. Depending on the line before it and the blank lines around it, a run of dashes may act as a setext heading underline or a thematic break (horizontal rule). If the result is ambiguous to you, make the intended structure explicit: use an ATX heading such as # Heading, or separate blocks with blank lines where appropriate. Then confirm the output in the target renderer.
How do I force a line break in Markdown?
A single newline inside a paragraph does not necessarily create a visible line break. Under CommonMark, a hard break can be made with a backslash at the end of the line or with two spaces at the line end. Trailing spaces are easy to miss in ordinary editors, so the backslash convention is often clearer when the destination supports CommonMark. Preview the result to verify that the renderer applies the rule you expect. The CommonMark documentation describes both conventions.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Why are tables or other Markdown features showing as plain text?
Tables, task lists, autolinks, footnotes and math are not universally supported extensions. GFM defines tables, task lists and autolinking on top of CommonMark, but another renderer may implement only core syntax or choose a different set of extensions. GitHub’s GFM announcement describes that relationship and the added features.
When comparing two destinations, check the specific dialect and extensions each supports rather than asking which one is universally “correct.” Also compare their handling of line breaks, list indentation, fenced and indented code, raw HTML, and whether the preview matches the final publishing destination.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Quick Recap
Best Value
How to find the cause of a Markdown rendering problem
- Name the destination. Identify where readers will see the document: a repository page, issue comment, documentation site, note-taking app or another renderer.
- Check the dialect and extensions. Find out whether the destination uses CommonMark, GFM or another variant, and whether the feature at issue is supported there.
- Preview the exact destination. Use its own preview when possible, or a parser configured for the same dialect. A generic editor preview may follow different rules.
- Find the earliest divergence. Compare source and output at the first unexpected change. Inspect nearby blank lines, trailing spaces, indentation, list-marker changes, heading underlines and opening or closing code fences.
- Make the structure explicit. Add blank lines where appropriate, use consistent list markers and indentation, and prefer an unambiguous heading form when a line of dashes could be read another way. Preview again after editing.
- Check raw HTML separately. If the document mixes HTML and Markdown, verify how the destination handles HTML blocks and which sanitization rules it applies. Implementations have differed in this area.
What to check when two renderers disagree
- The core specification or dialect each supports, such as CommonMark or GFM.
- Which extensions are enabled, including tables, task lists, autolinks, footnotes or math.
- How each handles line breaks, list indentation, fenced and indented code, and raw HTML.
- Whether the preview reflects the final publishing destination.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
