Free tools Windows power users keep installed
One-click scans. No signup required.
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 formatting fails for three main reasons: the destination uses a different Markdown dialect, the source structure does not match the parser’s rules, or the editor is displaying a mode or setting that changes how syntax is interpreted. The same text can therefore render correctly in one application and appear as literal punctuation, collapsed lines, or malformed blocks somewhere else.
Start with the destination, not with random edits. Identify the exact application and output path, check its documented dialect, reduce the failing text to a minimal example, inspect its surrounding structure, and validate the result in the final place where readers will see it.
| # | Preview | Product | Price | |
|---|---|---|---|---|
| 1 |
|
The Markdown Guide | $7.95 | Buy on Amazon |
| 2 |
|
Using Markdown: A Short Instruction Guide | $9.99 | Buy on Amazon |
| 3 |
|
Markdown: A Complete Guide | $9.99 | Buy on Amazon |
| 4 |
|
Accessible Markdown: Structured Authoring and Reliable Exports | $19.99 | Buy on Amazon |
| 5 |
|
R Markdown Cookbook (Chapman & Hall/CRC The R Series) | $24.87 | Buy on Amazon |
What actually determines Markdown rendering
Markdown is a source format interpreted by a parser. The parser turns characters into paragraphs, headings, lists, links, code blocks, tables and other elements; the destination then applies its own preview, sanitization and publishing rules. “Markdown” is therefore not one perfectly identical language implemented everywhere.
Dialect and extension support
CommonMark documents a formal core syntax, while GitHub Flavored Markdown (GFM) adds features such as tables and task lists. An application that implements only core syntax may display an extension literally or parse it differently. Conversely, two applications can both claim Markdown support while making different choices about edge cases.
#1 Best Overall
GitHub described the compatibility problem when announcing its formal specification: “Things like how many spaces are needed to indent a line, how many empty lines you need to break between different elements, and a plethora of other trivial corner cases change between implementations: very similar looking Markdown documents can be rendered as wildly different outputs depending on your Markdown parser of choice.” See the GitHub Blog explanation for that context.
Block structure and context
Markdown is contextual. A line can be ordinary paragraph text, a list continuation, a quotation, or code depending on the lines around it. Blank lines, indentation, marker characters and opening or closing delimiters all affect the parse. Fixing a single character without checking the surrounding block can move the problem rather than solve it.
Editor mode and destination processing
An editor may show source text instead of rendered preview, while a publishing host may sanitize raw HTML or apply its own line-break rules. A local preview is evidence about that preview’s parser, not proof of what another host will publish. GitHub’s own guidance explains its rendering environment in Using Markdown and Liquid in GitHub Docs and its broader formatting behavior in About writing and formatting on GitHub.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →A reliable troubleshooting sequence
Use this order so that you do not spend time changing valid syntax that the destination simply does not support.
- Name the destination. Record the application, platform, document type and final output path: for example, a repository file, an issue, a documentation page or an editor preview. Do not assume that a feature supported in one GitHub surface or another application behaves identically elsewhere.
- Read the destination’s current Markdown documentation. Confirm which dialect it uses, whether it supports extensions, and whether raw HTML, hard breaks or embedded content are restricted. Use the host’s own examples as the reference for final behavior.
- Classify the syntax. Decide whether the failing feature is part of CommonMark or an extension such as a GFM table or task list. If it is an extension, verify explicit support before changing spacing or punctuation.
- Make a minimal reproduction. Copy only the smallest block that still fails into a clean document using the intended destination’s preview. Remove surrounding headings, lists, quotes, HTML and unrelated paragraphs.
- Reintroduce context gradually. Add the removed lines back one block at a time. The first addition that changes the result identifies the boundary, indentation or delimiter interaction causing the failure.
- Inspect structure. Check blank lines around paragraphs and block elements, indentation relative to list markers, quote markers, matching fence delimiters, and characters that may have been escaped or converted by a copy-and-paste operation.
- Check the viewing mode and settings. Confirm that the application is in rendered preview rather than source mode. Look for a line-break setting or a mode that treats the file as plain text; the exact label is product-specific, so consult that product’s documentation.
- Validate after publication or paste. Render the minimal example in the actual final destination, then test the complete document. The target parser and sanitization rules control the result readers receive.
Fixes for common symptoms
Raw asterisks, hashes or backticks appear
First determine whether you are looking at source mode. If the entire document shows punctuation such as heading markers, emphasis markers or backticks, switch to the application’s rendered preview. If only one region is literal, check whether it is inside a code block or inline-code span, where Markdown punctuation is intentionally displayed as text.
If preview mode is correct, check dialect support and the exact syntax documented by the destination. A parser that does not recognize a feature will not make it work merely because the characters are arranged correctly. Reduce the feature to one short example and compare it with the host’s official example before adding complexity.
A new source line does not create a visible line break
A newline in the source can be a soft line break: it separates source lines while remaining within the same rendered paragraph. If you intend a new paragraph, leave a blank line and start a new paragraph block.
Recommended Free Tools
For a hard line break within one paragraph, CommonMark recognizes either two or more trailing spaces or a backslash at the end of the line. In source form, the pattern is:
First line
Second lineSome destinations alter, disable or sanitize these behaviors, so verify the result in the final host. Do not rely on visually wrapping a long source line; wrapping in the editor is not the same as inserting a hard break.
Trailing spaces are especially easy to lose during trimming, auto-formatting or a copy operation. A backslash is more visible in source, but it still depends on the destination honoring CommonMark’s hard-break rule. If the intended meaning is a separate thought, a blank line and a new paragraph are usually clearer and more portable than forcing a break.
A list absorbs following text or nesting looks wrong
List parsing depends on the marker, indentation and nearby blank lines. Check that each item uses a consistent marker style, that continuation text is indented far enough for the destination’s rules, and that a nested item is aligned beneath the content of its parent rather than arbitrarily beneath the marker.
Test the smallest possible list first:
- Parent item
- Nested item
Paragraph outside the list.If the paragraph is absorbed into the final item, inspect whether a blank line is required by the target parser. If nested content is displayed as ordinary text, compare its indentation with the destination’s documented examples. Quotation markers and lists can also interact, so isolate each structure before combining them.
Do not diagnose indentation from the rendered appearance alone. A proportional font can make different counts of spaces look aligned, and tabs can expand to different widths. Inspect the actual characters, replace tabs with spaces when alignment matters, and test a single nested item before restoring the full list. A list that works by itself may change when placed inside a block quote or immediately after a fenced block.
A code block continues too far or closes too soon
Use a matched pair of fences and put the closing fence on its own line. The opening and closing fences should use the same character, normally backticks or tildes; the closing fence must be at least as long as the opening fence. A language label belongs on the opening fence only when the destination supports syntax highlighting.
```text
example content
```
Text outside the code block.If code content itself contains a sequence that could close the fence, choose a longer fence for the outer block. Check for an accidentally deleted closing delimiter, trailing characters on the closing line, or indentation that causes the fence to be interpreted as ordinary text. Compare the result with the target platform’s code-fence examples.
When a block appears to swallow headings or paragraphs after it, inspect the closing line before changing anything inside the code. A closing fence with extra text, the wrong character, or insufficient length may not close the block. Conversely, a short fence appearing inside the example can terminate it earlier than intended; lengthening the outer fence is safer than escaping every character in the code sample.
Rank #3
A table shows pipes and dashes literally
Pipe tables are documented by GFM, not by every Markdown implementation. Confirm that the destination supports GFM or an equivalent table extension. The delimiter row is required in GFM-style tables; changing column spacing cannot compensate for an unsupported extension.
| Name | Status |
| --- | --- |
| Build | Passing |If the document must travel through destinations with different capabilities, use syntax common to all of them, or keep a rendered or exported representation for the less capable destination. Do not assume that a table working in a GitHub preview will work in an unrelated editor.
When only some cells look wrong, check the pipe characters inside cell content as well as the delimiter row. A pipe intended as literal text may be interpreted as a column separator unless the destination documents an escaping method. Test a two-column table first; adding alignment markers, long cells or embedded formatting before basic support is confirmed makes the diagnosis harder.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsFormatting disappears after moving between applications
Compare the feature against both dialects and processing pipelines. Copying can introduce smart quotes, alter whitespace, remove trailing spaces, escape punctuation, or place content inside a code span. A destination may also sanitize raw HTML or remove constructs it does not permit.
Paste the smallest failing block as plain text into the final host, then rebuild it with the host’s documented syntax. When portability matters more than extension features, prefer core CommonMark constructs and avoid relying on raw HTML or renderer-specific extensions.
Structural checks that prevent most failures
Blank lines and block boundaries
Use blank lines to make paragraph, list, quote and code-block boundaries unambiguous. A heading followed immediately by text usually works, but a list or fenced block placed directly against another structure can be interpreted as a continuation. When a block is unexpectedly joined to the previous one, insert a blank line and retest.
Blank lines are diagnostic, not a universal cure. Add one at a time and observe which boundary changes. If a blank line has no effect, the issue may be an unsupported extension, an unmatched delimiter or the wrong viewing mode rather than paragraph separation.
Indentation and nesting
Count spaces rather than relying on visual alignment in a proportional-font editor. List continuation, nested lists, indented code and block quotes each have their own indentation rules. Tabs can display at different widths and should not be mixed casually with spaces when alignment determines structure.
Delimiters and escaping
Every opening construct should have a compatible closing construct: emphasis markers, code spans, fenced blocks and links are common examples. A missing delimiter can make the parser consume many following lines. If punctuation is meant to be literal, escape it only where the destination’s syntax calls for escaping; excessive backslashes can create a different failure.
For a systematic check, temporarily remove emphasis, links and inline code from the failing paragraph. Restore one construct at a time and verify its closing marker. This isolates whether the visible problem is a block-level error or an inline delimiter that changes how the rest of the line is tokenized.
Raw HTML and sanitization
Some renderers pass selected HTML through, while others display it as text or remove it for security. If a layout depends on HTML, verify that the destination permits that element and attribute. For portable documents, use Markdown constructs supported by every target instead of assuming raw HTML will survive the trip.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
How to compare renderers before choosing a workaround
When two previews disagree, compare them on the specific dimensions that affect the failing feature rather than asking which one is “more correct.” Record whether each parser follows CommonMark, adds GFM or another extension, treats a source newline as a soft break, permits raw HTML, and sanitizes tags or attributes. Also note whether you are comparing an editor preview with published output; those can be separate processing stages even within one service.
Run the same five-block test in each destination: a heading and paragraph, a list with one nested item, a fenced code block, a block quote and a table if tables matter to the document. Keep the source identical. Differences in only the table indicate extension support; differences in ordinary paragraphs or fences point to dialect or structural handling. This controlled comparison is more useful than repeatedly adjusting a production document whose surrounding context may hide the first failure.
If the document has one authoritative destination, optimize for that host’s documented behavior and test there. If it must remain editable in several unrelated applications, choose core syntax, avoid renderer-specific HTML, and accept that some presentation features may need to be represented as plain paragraphs or a separately rendered artifact.
Choosing a strategy when documents must be portable
| Decision point | Prefer | Why it matters |
|---|---|---|
| One known destination | That destination’s documented dialect | You can use supported extensions and validate against the actual renderer. |
| Several unrelated Markdown applications | Core CommonMark syntax where possible | Extensions and edge-case parsing are less likely to transfer consistently. |
| Tables or task lists are essential | A destination that explicitly supports the relevant extension | GFM features are not guaranteed in a non-GFM parser. |
| Output must be identical after export | Render and inspect the exported or published artifact | Preview behavior alone does not establish final output or sanitization. |
| Raw HTML is required | Use it only after checking the host’s allowlist | Sanitization can remove elements, attributes or entire blocks. |
The most portable document is not necessarily the most feature-rich one. Decide whether your priority is extension functionality in one host or predictable rendering across several hosts, then write and test accordingly.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Minimal diagnostic examples
A controlled example helps distinguish a parser limitation from a structural error. Create a new file containing one paragraph, one heading, one list, one fenced block and, if relevant, one table. Render it in the intended destination. If the heading, paragraph and list work but the table is literal, the likely issue is extension support rather than general Markdown failure.
Best Value
Next, add the original document’s surrounding elements one at a time: a block quote, nested list, HTML fragment, or preceding code fence. If the simple feature changes only after one addition, inspect that boundary for a missing blank line, unmatched delimiter or indentation shift. Keep the reduced example while reporting the problem; it communicates the failure more clearly than a full document with unrelated content.
Final validation checklist
- The exact destination and document type are recorded.
- The destination’s current dialect and extension support are confirmed.
- The failing feature has been reduced to a minimal example.
- Blank lines, indentation, markers and delimiters have been inspected.
- Source mode and rendered preview have been distinguished.
- Line wrapping has not been mistaken for a hard line break.
- Tables and task lists have been checked for explicit extension support.
- Code fences open and close cleanly, with the closing fence on its own line.
- Raw HTML has been checked against the destination’s sanitization behavior.
- The complete document has been tested in the final published or pasted location.
When to stop changing the source
If a minimal, structurally valid example still renders literally in the destination, the remaining explanation may be that the feature is unsupported or disabled. At that point, repeated spacing changes are unlikely to help. Replace the feature with a supported equivalent, choose a renderer that implements the needed extension, or provide a rendered artifact for that destination. This is a compatibility decision, not evidence that the original Markdown was malformed.
Frequently Asked Questions
Why does my Markdown work on GitHub but not in another editor?
GitHub uses GitHub Flavored Markdown, which extends CommonMark with features such as tables and task lists. Another editor may implement only core syntax or make different parsing choices. Check the second application’s dialect documentation and test the feature in a minimal file.
How do I force a Markdown line break?
For a new paragraph, insert a blank line. For a hard break within one paragraph, CommonMark recognizes two or more trailing spaces or a backslash at the end of the line. Confirm that the destination preserves and renders that syntax.
Why is my Markdown table showing pipes and dashes?
Pipe tables require GFM or an equivalent table extension, including a delimiter row. If the destination does not support that extension, spacing changes will not help; use a supported alternative or a rendered table.
Why does a list include the paragraph after it?
The parser may be treating the paragraph as a continuation because of missing blank lines or indentation. Test a short list, add the documented boundary, and compare indentation with the destination’s examples.
Why does my fenced code block not close?
Check that the closing fence uses the same character, is on its own line, and is at least as long as the opening fence. If the code contains the same fence sequence, use a longer outer fence.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteShould I use raw HTML to fix Markdown formatting?
Only when the destination explicitly permits the required element and attributes. Some hosts display HTML as text or sanitize it. For portability, prefer Markdown constructs supported by every target.
The Bottom Line
Markdown failures are usually parser, structure or destination problems—not random punctuation problems. Identify the target dialect, isolate the smallest failing block, check blank lines, indentation and delimiters, distinguish soft wrapping from hard breaks, and validate in the final published location. When a valid minimal example still fails, switch to a supported syntax or renderer instead of endlessly adjusting spacing.
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.
