Understanding HTML ⇄ Markdown
A markup language and its writer-friendly cousin.
Markdown is HTML's shorthand. The conversion in either direction is mostly clean — the rough edges are predictable.
Markdown is a subset.
Almost every Markdown document round-trips cleanly to HTML and back: headings, bold and italic, lists, links, images, blockquotes, code blocks, horizontal rules, tables (in GitHub-flavoured Markdown). The conversion is unambiguous because Markdown's grammar maps element-for-element to a subset of HTML.
What HTML loses going to Markdown.
Anything Markdown can't express survives only as raw HTML embedded in the output (most parsers allow this) or disappears. Think: <div> wrappers, classes and IDs, <style> and <script> tags, custom data attributes, complex nested tables. Treating Markdown as a lossy projection of HTML is the honest mental model.
Flavours and parsers.
"Markdown" is a family of dialects: original Gruber Markdown, CommonMark (the modern reference), GitHub Flavoured Markdown (adds tables, task lists, strikethrough, autolinks), MDX (Markdown plus JSX). This tool produces and accepts CommonMark with GFM extensions — the dialect most parsers understand. If you target a specific renderer (Gatsby, Next.js MDX, Hugo) verify the output looks right there too.
Whitespace is significant in Markdown.
Two spaces at the end of a line become a hard line break. A blank line separates paragraphs; leaving it out merges two paragraphs into one. Code fences need an empty line above them or they read as inline code. The cure for most rendering surprises is to look at the source whitespace rather than the rendered output.
When to write which.
Markdown for prose-first content: README files, blog posts, docs, GitHub issues, anything you'd otherwise write in a word processor. HTML for interactive pages, anything with custom layout, anywhere CSS classes need to attach. The two coexist naturally — most Markdown processors will render embedded HTML untouched.