Markdown to HTML: What Actually Happens When You Hit Publish

Your post looked perfect in the editor.

Then you hit publish, opened the live page, and something was off. The nested list went flat. The bold text rendered as literal asterisks. A blockquote turned into a normal paragraph. You didn't change anything. So what happened?

A conversion happened. One you never see and rarely think about: markdown to HTML.

Understanding that single step explains most of the "it looked fine in my editor" bugs you've ever hit. So let's look at what's actually going on under the publish button.

Markdown to HTML is a translation, and translations lose things

Markdown is for humans. You write **bold** because it's faster and cleaner than typing out tags. But browsers don't read markdown. They read HTML.

So every tool that publishes markdown runs a converter in between. It reads your **bold** and emits <strong>bold</strong>. It turns # Heading into <h1>Heading</h1>, and - item into a <ul><li> structure.

When it works, you never notice. When it breaks, you get the mystery from the top of this post.

And here's the catch that trips everyone up: there is no single markdown standard. There's CommonMark, GitHub Flavored Markdown, and a dozen converters that each interpret the edge cases differently. The markdown that renders cleanly in one tool can mangle in another, because a different converter made a different guess.

That's why "it rendered in my editor" is not the same as "it'll render on my blog." Your editor used one converter. Your blog uses another.

Where the conversion silently breaks

Four spots account for most of the damage. None of them throw an error. They just quietly do the wrong thing.

Nested lists. This is the number one casualty. Indent a sub-bullet with the wrong number of spaces and the converter can't tell it's a child. It either flattens the whole thing into one level or, worse, drops your nested item into a code block. Most converters want a consistent two or four spaces. Mix tabs and spaces and you're rolling dice.

Raw HTML. People reach for raw <div> or <video> tags when markdown can't do what they want. Sometimes it works. Often it doesn't, because many converters strip raw HTML for security, to stop pasted content from injecting scripts. Your tag vanishes with no warning. The fix is almost always to use the markdown equivalent and let the converter emit clean, trusted HTML.

Smart quotes and dashes. Some converters "helpfully" turn straight quotes into curly ones and double hyphens into long dashes. Lovely for prose, a disaster inside a code sample, where a curly quote is a syntax error your reader will copy and paste straight into a crash.

Line breaks. In most markdown, a single newline does nothing; you need a blank line to start a new paragraph, or two trailing spaces to force a <br>. Writers who hit Enter once and expect a line break get a run-on paragraph instead, because the converter merged their lines exactly as the spec told it to.

The mental model that fixes most of this

Stop thinking "I wrote it, so it'll appear." Start thinking "I wrote a source, and a converter will interpret it."

That one shift changes how you write:

• Be explicit with structure. Blank lines between blocks. Consistent list indentation. Don't make the converter guess.
• Avoid raw HTML in the body. If markdown has a way to express it, use that way.
• For code, wrap it in proper fences with a language tag, so no converter "fixes" your quotes.
• Preview on the destination, not just in your editor, because they may not run the same converter.

Do that and most of the mystery breakage disappears, because you stopped fighting the conversion and started writing for it.

When one source has to land in four different converters

Here's where it gets genuinely hard. You're not publishing to one place. The same post goes to your blog, your newsletter tool, X, and LinkedIn, and every one of them runs a different conversion with different rules. The markdown that renders clean on your blog can flatten in your email tool and turn to literal asterisks on X, which supports no formatting at all.

You can reshape your source by hand for each destination, every time. It works. It also eats the afternoon you wanted to spend writing.

Or you keep one clean markdown source and let a tool handle the per-destination conversion. That's what Writeous does. Paste one markdown file and get back a blog post, a newsletter, an X thread, and a LinkedIn post, each converted and formatted for where it's going, in about a minute. The blog post gets real HTML. The X version drops the formatting X can't render. The newsletter comes back email-shaped. Free to try, no login.

One honest note: when your blog runs on Ghost, Writeous re-syncs the published post in place, so editing your source updates what's live. Social goes out through Typefully and works, but a sent post can't be edited after the fact, so we call that best-effort, not true sync. Better to name the limit than imply one that isn't there.

The takeaway

There's a converter between what you write and what your reader sees. It's usually invisible, occasionally hostile, and never the same twice across platforms.

Write a clean, explicit source. Preview where it'll actually land. And when the same source has to survive four different conversions, let something handle the translation so you can get back to the part that's actually yours: the writing.

Write once. Publish everywhere. Actually.