iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Markdown source is plain text; a parser—not the way it looks in your editor—decides whether it becomes a paragraph, list, heading, code block, or something else. The destination matters, too: GitHub Flavored Markdown (GFM), CommonMark, and other Markdown dialects do not necessarily interpret every feature the same way. To diagnose a surprise, preview in the intended destination and inspect the source immediately before the first place the output diverges.
Why does Markdown look different when rendered?
Markdown is markup written in plain text and interpreted by a processor. The source can look obvious to a person while leaving the parser to apply rules about whitespace, line boundaries, and block structure. As the CommonMark project puts it, “The spec is written from the point of view of the human writer, not the computer reader.” Its specification project set out to make behavior more predictable because Markdown’s early syntax description left choices open, including how lists, line breaks, and HTML blocks should be handled. CommonMark specification project README
That is why identical text can render differently on different sites or in different apps. GitHub reported that less than 1% of its existing user content was estimated to be affected by its CommonMark-based renderer transition. That was a GitHub-specific 2017 estimate: the company rendered content with its older Sundown parser and the new cmark implementation, normalized the HTML, and compared the output trees. It is not a general error rate for Markdown files or platforms. GitHub Engineering’s 2017 migration account
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteCheck the dialect before troubleshooting a feature
CommonMark formalizes core Markdown behavior. GFM is based on CommonMark and defines additional features, including tables, task lists, and autolinking. Those extensions are not guaranteed in every renderer. A table that works in a GitHub repository may remain literal text in a destination that does not support GFM tables. Check the destination’s documented dialect and extensions rather than treating “Markdown” as one universal standard. GitHub Flavored Markdown Spec · GitHub’s GFM announcement
#1 Best Overall
Why is my Markdown list or heading formatting wrong?
Markdown uses surrounding context as well as the characters on a line. A blank line, indentation, or a changed marker can alter how the parser groups the text. GitHub’s GFM specification gives formal examples of these block-level rules. GitHub Flavored Markdown Spec
Indentation can turn text into code
Four leading spaces can create an indented code block. Inside a list, continuation text is parsed according to its indentation relative to the list marker. If a heading or paragraph unexpectedly appears as code—or content seems to fall outside its list—compare the leading spaces on that line with the surrounding lines.
Rank #2
Dashes depend on context
A line of hyphens can serve as a setext heading underline or a thematic break, depending on the surrounding text and blank lines. When the intended structure matters, separate blocks clearly or use an ATX heading such as # Heading rather than relying on a dash line to signal what you mean.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Marker changes can split a list
Under CommonMark, changing bullet characters starts a new list; switching an ordered-list marker from a period to a closing parenthesis also starts a new list. The starting number of an ordered list is significant. Keep markers consistent when you want one continuous list, and check the target renderer if the numbering or grouping surprises you.
How do I force a line break in Markdown?
A single newline inside a paragraph does not necessarily render as a visible line break. CommonMark supports a backslash at the end of a line and the older convention of two spaces at the line end for a hard break. The spaces are easy to miss in an ordinary editor. When the destination supports CommonMark, the backslash convention is easier to see in source; in either case, verify the result in the intended renderer. CommonMark specification project README
Why are Markdown symbols showing instead of formatting?
Literal Markdown syntax often means the destination does not support the feature or dialect you used, or that the text is being displayed without Markdown processing. For example, a GFM table or task list may not be recognized by a renderer that implements only a different subset. Confirm that the destination parses Markdown and supports the specific extension; a preview in another editor does not prove the publishing destination will render it.
A practical way to debug unexpected Markdown
- Name the destination. Identify where the document will appear, such as a repository page, issue comment, documentation site, or note-taking app.
- Check its dialect and extensions. Find out whether it supports CommonMark, GFM, or another variant, and whether the feature you used is an extension.
- Preview there. Use the destination’s own preview when available, or a parser configured for the same dialect. A generic editor preview may follow different rules.
- Find the earliest divergence. Start at the first unexpected rendered element and inspect the source just before it. Look for blank lines, invisible trailing spaces, indentation, changed list markers, heading underlines, and opening or closing code fences.
- Make the structure explicit. Add appropriate blank lines, use consistent list markers and indentation, and prefer unambiguous heading syntax. Preview again after each change.
- Check HTML separately. If Markdown is mixed with raw HTML, verify how the destination handles HTML blocks and which HTML it allows. CommonMark identifies HTML-block behavior as an area where implementations have differed.
What to compare when two renderers disagree
- The core specification or dialect each renderer supports.
- Support for extensions such as tables, task lists, autolinks, footnotes, or math.
- How each handles line breaks, list indentation, fenced and indented code, and raw HTML.
- Whether the preview accurately matches the final publishing destination.
There is no universally correct rendering independent of context: the useful reference is the dialect and behavior of the place where readers will see the document.
Free tools Windows power users keep installed
One-click scans. No signup required.
Quick Recap
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.
