Why the Same Markdown File Renders Differently Everywhere

Quick answer

Markdown was never one standardized language. Every app that renders it built its own dialect on top of a loosely defined original description — so the same .md file can look right on GitHub and come out broken in your text editor. Two things cause this. The original syntax left real questions unanswered. And popular tools each bolt on their own extensions — tables, task lists, footnotes — that only render where they're actually supported. Below: why the gaps exist, which syntax is safe everywhere, and how to write Markdown that holds its shape wherever it lands.

How it actually works

Markdown was never fully specified

John Gruber, Markdown's creator, designed it as a writing format, not a publishing format — readable plain text came first, formatted output second. That kept the syntax minimal. It also left gaps. The original description doesn't fully specify indentation rules for nested lists, when a blank line is required before a heading or blockquote, or how list items interact with paragraph tags. Early implementers filled those gaps by copying the behavior of the original reference script, Markdown.pl — a script its own successors describe, bluntly, as buggy and inconsistent. And because Markdown has no concept of a syntax error, none of this throws a warning. An ambiguous file just renders as something. You only notice the divergence when you put two outputs side by side.

Flavors layer different extensions on the same core

CommonMark exists to fix exactly that — a formal, unambiguous spec for the core syntax, backed by a conformance test suite. GitHub Flavored Markdown (GFM) builds on top of it as a strict superset, adding tables, task lists, strikethrough, and autolinks as opt-in extensions. Other flavors add different things entirely: GitLab Flavored Markdown, Markdown Extra, and MultiMarkdown each support their own mix of footnotes, math, and custom heading IDs, and almost no two flavors match feature-for-feature. It shows up in small ways too. ATX vs Setext heading rules differ across parsers, and whether a # needs a trailing space before it counts as a heading isn't universal either. GitHub's own alerts and task lists make the point well: they're GitHub-specific extensions, so they render as intended on GitHub and as plain punctuation anywhere that only implements bare CommonMark.

When to use it (and when to skip it)

Extended syntax is safe when you control both ends — writing and previewing inside the same app, so you already know what it supports. It gets risky the moment a file needs to travel. A GitHub README, a static site generator, a note-taking app, and a documentation platform can all disagree on the very same file. When that's the case, stick to syntax every flavor agrees on: headings, lists, emphasis, links, images, blockquotes, and fenced code blocks all render the same almost everywhere. Treat tables, footnotes, and other extensions as bonus syntax — use them once you've confirmed the destination actually supports them, not before. There's no single canonical chart for this, either. Community tools like Babelmark exist because writers still discover parser differences by trial and error, running the same snippet through several parsers just to see where the output splits. It's a real trade-off: fewer extensions means less visual richness, but far more certainty your file looks the same wherever it's read. Keeping your Markdown consistent is an ongoing habit, not a one-time cleanup — and it's part of why plain text keeps winning out over rich text for writers who move files between tools.

How Carets fits in

This is exactly the problem plain text is supposed to solve, and it's why Carets treats your files as plain text from the moment you write them. Carets renders standard Markdown and GFM predictably, so what you see while writing is what shows up wherever the file goes next — nothing about the source changes when it leaves the app. Files, projects, and tags keep your notes organized, so you always know which version of a file or a README is current, on iPhone, iPad, or Mac. Your work stays portable and future-proof, because the file itself — not a proprietary format — is the source of truth. Carets is a fast, native notes and code editor for iPhone, iPad, and Mac. Download it from the App Store and see how your Markdown looks the same everywhere you take it.

Frequently Asked Questions

Why does my Markdown file look different on GitHub than in my code editor?

Every Markdown renderer interprets Gruber's original, intentionally loose description its own way. GitHub renders with GitHub Flavored Markdown (GFM), which adds tables, task lists, and strikethrough on top of the CommonMark core. Your editor's preview pane might implement only bare CommonMark, or a different flavor like Markdown Extra — so anything outside the shared core can render, or fail to render, differently.

What is CommonMark, and does every tool support it?

CommonMark is a formal, unambiguous specification for the core Markdown syntax, created because Gruber's original description left many parsing rules undefined. Most modern parsers — GFM included — build on CommonMark as a base. Plenty of older or niche tools still follow their own interpretation, though, so "CommonMark-compliant" isn't universal.

Are GitHub-only features like task lists and tables safe to use everywhere?

No. Task lists, tables, and strikethrough are GFM extensions, not part of core CommonMark. They'll render correctly on GitHub and other GFM-compatible tools. A plain CommonMark renderer — or an app that only implements the base spec — will show the raw syntax as literal text instead of a formatted table or checkbox.

How can I write Markdown that renders consistently across tools?

Stick to the syntax common to every major flavor — headings, lists, emphasis, links, images, blockquotes, and fenced code blocks all work the same almost everywhere. Treat tables, footnotes, and other extensions as bonus syntax you use only once you know the target renderer supports them, and avoid raw HTML unless you've confirmed the destination allows it.

Does raw HTML embedded in a Markdown file always work?

Not always. Gruber's original design treats raw HTML as Markdown's built-in escape hatch for anything the syntax can't express, but some renderers sanitize or strip HTML entirely for security reasons. GitHub, for instance, allows a limited safe subset and removes the rest — so HTML that works in one place may vanish in another.

Conclusion

Rendering differences aren't a bug in any one tool. They're the predictable result of a syntax that was never fully standardized, then extended piecemeal by every platform that adopted it. Write to the common core, know exactly which extensions you're relying on, and your Markdown file will look the same wherever it lands next.