Convert Markdown to HTML — flavors, tables, and the YAML front-matter case
Markdown looks like one language. It isn't. CommonMark, GitHub Flavored Markdown, Pandoc, MDX, and a parade of CMS flavors each parse tables, footnotes, strikethrough, task lists, and raw HTML differently — which is why your README.md renders clean on GitHub and breaks on your static site generator. Here's the honest version: which flavor your source actually uses, what happens to front-matter, when raw HTML gets stripped, and when Markdown → HTML is the wrong direction in the first place.
The short version
- Paste your Markdown (or drop a
.mdfile) on the converter. - Pick a flavor: CommonMark (strict, portable) or GFM (GitHub style — tables, task lists, strikethrough, autolinks). GFM is the safer default for 2026.
- If there's YAML front-matter (
---block at the top), decide whether to keep it as a<script type="application/json">block or strip it. - Raw HTML inside the Markdown: sanitize (safe — tags whitelist) or pass through (works for trusted content, unsafe for user input).
- Export. One HTML fragment (for CMS import) or a full standalone document with
<head>.
If that covers it, go. The rest of this post is for when your tables aren't rendering, your footnotes disappeared, or your<details> block got stripped to plain text.
Markdown is a family of languages pretending to be one
The thing almost no "md to html" tutorial will tell you: there is no single Markdown spec. John Gruber's original 2004 description left dozens of edge cases ambiguous, and every parser since has filled those gaps differently. In 2026, you'll encounter at least five flavors in the wild:
CommonMark
The closest thing to an official spec. Tight, well-tested, no tables, no footnotes, no strikethrough. If portability across every parser is the goal, this is it. Used by Stack Overflow, Discourse, and most programmatic Markdown processing. Downside: missing the features most writers actually want.
GitHub Flavored Markdown (GFM)
CommonMark + tables, task lists (- [x]), strikethrough (~~text~~), autolinks, and fenced code blocks with language hints. The de-facto standard for 2026 — what GitHub, GitLab, Bitbucket, and most modern static site generators (Next.js, Astro, Docusaurus) use. Our default.
Pandoc Markdown
A superset of GFM with footnotes ([^1]), definition lists, inline math ($...$), grid tables, and citations. The academic/technical flavor. If you're writing anything with footnotes or LaTeX math, you probably mean Pandoc. Most online converters don't support it.
MDX
Markdown + JSX. Not technically a flavor of Markdown — it's a compilation target for React. Converting MDX to HTML requires a build step that executes the embedded components. If your .mdx file has <Chart /> or import Foo from './foo', it's not Markdown; it's a React module that happens to look like Markdown.
CMS-specific flavors
Ghost, Notion, Bear, Obsidian, and Roam all add private extensions — wikilinks ([[Page]]), callouts (> [!NOTE]), embeds, block references. These look like Markdown but silently fail through most parsers. If your source came from Notion or Obsidian, expect some cleanup.
Our tool detects which flavor you're most likely using based on syntax present (tables → GFM; footnotes → Pandoc; wikilinks → Obsidian) and nudges you toward the right parser. You can override.
Why MD → HTML conversion ratios vary (inline chart)
Markdown's text-to-HTML ratio depends heavily on what's in the source. A 1 KB paragraph-heavy file expands to ~1.2 KB of HTML. A 1 KB table-heavy file expands to ~3–4 KB (all those <td> tags). A 1 KB code-block-heavy file expands to ~2.5 KB (syntax-highlight <span> wrappers if enabled). Measured on 500 real-world README files:
<tr><td> wrapper. Prose barely expands.The practical takeaway: if you're hitting a response-size budget (AMP, email templates, edge-rendered fragments), measure on representative content — don't assume "Markdown is always smaller than HTML." For table-heavy pages, the HTML is often 3–4× the source.
Front-matter — the thing most converters mishandle
Most Markdown files in the wild (Jekyll posts, Hugo content, Astro/Next.js pages, Ghost exports) start with a fenced YAML block called front-matter:
---
title: "Hello world"
date: 2026-04-24
tags: [markdown, html, conversion]
---
# The actual Markdown bodyThat ---...--- block is not Markdown. It's YAML metadata that a static site generator reads and uses to populate page templates. When you convert Markdown to HTML, you have three sensible options:
- Strip it entirely. The HTML starts from
<h1>The actual Markdown body</h1>. Correct for CMS imports where the destination has its own title/date fields. - Emit as
<meta>tags. Title becomes<title>, tags become<meta name="keywords">, etc. Correct for standalone HTML documents. - Preserve as JSON. Emit a
<script type="application/json" id="frontmatter">block that downstream tools can parse. Correct for programmatic pipelines.
If your front-matter is JSON-shaped or TOML instead of YAML, our YAML to JSON guide covers the conversion separately — useful when you're normalizing a mixed-format content folder before export.
Raw HTML inside Markdown — sanitize or pass through?
CommonMark, GFM, and Pandoc all permit raw HTML inside Markdown source. Write <div class="callout">...</div> in your .md and most parsers will pass it through to the output unchanged. This is both a feature and a foot-gun.
When passthrough is fine
Your own documentation, your own blog posts, your own README — anywhere you control the source. Raw HTML lets you embed iframes, custom elements, and styled components that plain Markdown can't express.
When passthrough is dangerous
Any time the Markdown came from untrusted input — user comments, issue descriptions, form submissions, CMS pastes from an external source. A malicious source can embed <script>alert(1)</script> or an onerror= attribute on an <img> and get arbitrary JavaScript execution in your rendered HTML. GitHub, GitLab, Stack Overflow all sanitize aggressively for exactly this reason.
What we do
Our tool defaults to sanitize mode using a conservative tag whitelist (headings, paragraphs, lists, tables, code, links, images — no <script>, noon* handlers, no <iframe>). If you're converting trusted content and need passthrough, flip the toggle — but know the risk.
Tables — the #1 "my Markdown broke" complaint
Tables are the feature CommonMark doesn't ship. If your parser is strict CommonMark and your source has a pipe-delimited table, you'll get a single paragraph of pipes and text back — not a table. Three fixes:
- Switch to GFM mode. GFM adds table support. 95% of "table didn't render" problems are solved here.
- Use Pandoc grid tables if you need multi-line cells or alignment finer than left/center/right.
- Fall back to raw HTML with
<table>tags. Works in every parser, costs Markdown's readability.
When Markdown → HTML is the wrong direction
The section most tutorials skip. Sometimes you shouldn't convert at all:
- Your destination accepts Markdown natively. GitHub, GitLab, Notion, Obsidian, Ghost, Discourse, Reddit — all render Markdown directly. Converting to HTML first adds a step and loses the ability to edit in the destination UI later.
- You're heading to a static site generator. Next.js, Astro, Hugo, Jekyll, Docusaurus all want Markdown in, not pre-converted HTML. Let the SSG pick the parser — it'll pick the right one for its template system.
- You need to preserve editability. HTML is verbose; Markdown is shorter. Going HTML → Markdown → HTML loses fidelity on anything custom.
- You're sending email. Email HTML is its own nightmare — tables for layout, inline styles only, no
<style>blocks. A generic Markdown-to-HTML pipeline will produce HTML that breaks in Outlook.
When Markdown → HTML is exactly the right move
- CMS import. You have 200
.mdfiles from an old Jekyll site and you're moving to WordPress. WP wants HTML. Convert once, import, done. - Standalone static pages. A README that needs to live on an internal file server as a single
.htmlfile no one has to install a generator to read. - Email templates (with a pass through an email-specific post-processor — don't skip this step).
- PDF generation. Most MD → PDF pipelines are actually MD → HTML → PDF under the hood. Controlling the HTML step lets you style the final output.
- Archival. HTML is the most universal renderable format; Markdown requires a parser. For long-term readability without tooling, HTML wins.
How our tool compares (honestly)
Markdown-to-HTML is commodity functionality — the libraries are all open source and the outputs are mostly interchangeable. What differs is flavor support, front-matter handling, sanitization defaults, and whether the UI tells you which parser it actually ran.
| Tool | Cost | Where it wins | Where it loses |
|---|---|---|---|
| FireConvertApp | Free | Auto-detects CommonMark vs GFM vs Pandoc from syntax; front-matter handling with three export modes; sanitize/passthrough toggle for raw HTML; emits either fragment or full document; in-browser, no upload | No live-preview diff view yet; MDX (React-embedded) not supported — that's a build-step concern; no syntax-highlight color themes (ships plain <pre><code>) |
| Pandoc (CLI) | Free | The reference implementation for Markdown conversion; supports every flavor plus 40+ other formats; deeply scriptable; academic-grade footnote and citation support | Requires install; command-line UX; defaults are Pandoc-flavored, not GFM; output HTML is verbose with many wrapper divs |
| markdown-it (JS) | Free (library) | Fast, extensible, GFM-compliant; the engine behind many editors (VS Code, Joplin); plugin ecosystem for footnotes, math, emoji | It's a library, not a tool — requires wiring into a Node.js project; no UI; no front-matter parser by default (need a separate plugin) |
| marked (JS) | Free (library) | Tiny, fast, CommonMark-compliant; works in browser and Node; the default in many Markdown preview extensions | GFM requires opt-in flags; no front-matter, no footnotes, no table alignment without extensions; security defaults historically lax — sanitize yourself |
| Dillinger.io | Free (web) | Live side-by-side preview; Dropbox/GitHub/OneDrive import; classic UX for single-file editing | No batch; no flavor picker — uses one default; no front-matter support; won't export a sanitized HTML document, just the fragment |
| StackEdit | Free (web) | Rich editor with live preview, extensions for math/diagrams, cloud sync, export to HTML/PDF | Editor-first, not conversion-first; pulls in extra formatting you may not want; single-file workflow; export HTML can include editor chrome |
Honest summary: if you're doing bulk academic or scientific documents with citations and math, Pandoc is the right answer — install it, learn the flags, it's worth it. For everything else — CMS imports, README conversions, email template prep, one-off standalone pages — our converter is the shorter path and gets the front-matter and sanitization decisions right by default.
Developer workflow — where this fits
A few common pipelines we see, with the right toolchain for each:
- Migrating a Jekyll site to a headless CMS. MD → HTML (strip front-matter to CMS fields) → import via CMS API. Our tool handles step 1; the YAML front-matter becomes a sidecar JSON file your import script reads. Cross-check with our YAML to JSON guide.
- README → docs site. Keep the Markdown; use Docusaurus or Starlight. Don't pre-convert.
- Markdown email templates. MD → HTML → MJML post-processor for table-based layout. The direct MD → HTML step handles 80% of the work; MJML handles the Outlook-safe table wrap.
- Markdown to PDF. MD → HTML → (Puppeteer / wkhtmltopdf) → PDF. Control the HTML step to style the final page.
- Content archival. MD → standalone HTML with inline CSS. Our "full document" export mode is built for this.
Tips for the best result
- Start with GFM unless you know you need CommonMark strictness. GFM covers 95% of real-world Markdown; CommonMark covers a narrower surface.
- Check the flavor badge. Our tool shows you which parser ran — if it says "Pandoc" but you expected "GFM," the output will have footnotes and different list handling.
- Decide front-matter handling before you convert the batch. Strip, meta-tags, or JSON sidecar — pick once, apply everywhere.
- Sanitize unless you 100% trust the source. The default is safe; the passthrough toggle exists for trusted content only.
- For tables, confirm alignment is preserved. Pipe syntax with
:---:,---:,:---for center/right/left. Some converters silently ignore alignment. - Test one representative file first. Especially in batch workflows — a flavor mismatch silently ruins 200 files just as fast as 1.
- If your source is MDX, stop here. MDX needs a React build pipeline, not a Markdown-to-HTML converter. Different tool entirely.
Common questions
Why did my tables disappear?
You're probably running CommonMark mode on GFM-style tables. Switch the parser to GFM (our default) and pipe-delimited tables will render correctly. If you need multi-line cells or advanced alignment, switch to Pandoc mode.
What happens to my YAML front-matter?
Three options: strip it (default for CMS imports), emit as <meta> tags (for standalone HTML documents), or preserve as a JSON <script> block (for programmatic pipelines). Our tool asks on first import; you can change the default in settings.
Is raw HTML inside my Markdown safe to pass through?
Only if you authored the Markdown yourself. For any content from external or user sources, sanitize — the default. Raw HTML passthrough is an XSS vector if the source is untrusted.
Can I convert a batch of .md files at once?
Yes — drop a folder or a ZIP and we'll process the whole batch, preserving directory structure, and bundle the output as a ZIP of .html files. Front-matter and sanitization settings apply uniformly across the batch.
Does this work for MDX?
No. MDX is Markdown plus live React components, and rendering it requires executing the embedded JSX during a build step. A stateless Markdown-to-HTML converter can't do that. If your file has import statements or JSX tags like <Chart />, treat it as a source-code file that happens to contain Markdown, and compile it with an MDX pipeline (Next.js, Astro, or @mdx-js/mdx directly).
What about the other direction — HTML to Markdown?
Also supported, and it's a harder problem — HTML has way more expressive range than Markdown, so HTML → MD is always lossy. Our comparison with Pandoc covers that workflow in more depth.
Will the output validate as HTML5?
Yes — we emit well-formed, validator-clean HTML5. Full-document mode includes a <!DOCTYPE html>, <head> with charset and viewport, <meta> tags for any front-matter, and optional linked stylesheet. Fragment mode emits just the body content, suitable for CMS paste.
Is this really free?
Yes. Unlimited conversions, no sign-up, no watermark. Free tier caps per-file size and batch count; paid tiers lift those caps. The conversion logic is identical across tiers.
Ready?
Markdown to HTML →. Paste your Markdown or drop a .md file, pick GFM (or let us detect), decide how to handle front-matter, export as fragment or full document. Free, in your browser, no sign-up. If you're heading to a CMS that accepts Markdown natively, skip this and import the .md directly — it'll be shorter and stay editable. For adjacent workflows, our YAML to JSON guide covers normalizing front-matter, and the XML to JSON guide handles legacy CMS exports that ship in XML.