Markdown vs HTML for drafts

Published: 2026-09-05

When to draft in Markdown versus HTML, how GFM export and HTML import round-trip, and a local preview workflow that keeps unfinished docs in the browser.

Markdown and HTML both produce structured text for the web, but they sit at different layers. Markdown is a compact authoring language: headings, lists, links, and code fences that humans can edit in any text box. HTML is the delivery language browsers actually render—tags, attributes, and nesting that email clients, CMSs, and design systems often expect as the final artifact.

For most drafts—README notes, PR descriptions, internal docs, changelog blurbs—start in Markdown. Switch to HTML when layout, inline styles, or a downstream system require it. LocalTools’ Markdown live editor (Markdown Studio) gives you a GFM preview, HTML/rich-text export, and clipboard HTML import entirely in the browser.

Same content, different jobs

Concern	Markdown draft	HTML draft
Primary job	Author and review structure	Control exact markup / layout
Diff friendliness	Excellent in Git	Noisy; attribute and whitespace churn
Portability	READMEs, Issues, many SSGs	Email HTML, CMS fields, static pages
Learning cost	Low for everyday prose	Higher; more ways to nest and escape
Round-trip risk	Flavor-dependent features	Converting back to Markdown is lossy

Think of Markdown as the source of truth for writing, and HTML as a render or export format—unless your pipeline only accepts HTML, in which case HTML (or a template that emits it) is the source.

When Markdown wins

Git surfaces — GitHub, GitLab, and most code hosts render Markdown in READMEs, PRs, and comments. Reviewers already know #, lists, and fenced code.
Fast structure — Headings, task lists, and tables are fewer keystrokes than the equivalent tags. See GFM pipe tables when tables get messy.
Cleaner diffs — Changing a paragraph usually touches one line; changing a <div class="…"> can ripple across attributes and indentation.
Dialects you already use — GFM adds tables, strikethrough, task lists, and autolinks. Prefer the flavor your host documents; CommonMark-only renderers may drop GFM extras.

Example draft:

## Release notes

- Fix login redirect on Safari
- Add export to CSV

> **Note:** Feature flags stay off until Monday.

That paste works almost everywhere Markdown is accepted. The HTML equivalent is longer and harder to skim in a PR.

If you need a richer docs dialect than Markdown (admonitions, includes, book-scale structure), compare AsciiDoc vs Markdown—still prefer Markdown when the audience is GitHub-first.

When HTML wins

Email and rich paste — Many mail clients want HTML (or rich text derived from it). Export HTML or copy rich text from a Markdown preview when the destination is Gmail, Word, or a CMS “HTML” field.
Precise layout — Multi-column snippets, custom classes, and inline styles are HTML territory. Markdown has no portable way to express arbitrary CSS.
Downstream contracts — Some APIs and templates accept only HTML fragments. Drafting in Markdown then exporting once is fine; editing the exported HTML as the ongoing source may be clearer if teammates never touch Markdown.
Embedding widgets — Iframes, complex forms, and third-party embeds usually require raw HTML (and careful sanitization wherever that HTML is shown).

HTML drafts are still text files. Keep them local when they contain unreleased product copy or customer names—same privacy story as Markdown.

Round-tripping: Markdown ↔ HTML

Conversion is useful and not lossless.

Direction	Typical use	What you lose
Markdown → HTML	Preview, download `.html`, paste into email/CMS	Exact source whitespace; flavor-specific quirks if the exporter differs from your host
HTML → Markdown	Rescue a Word/CMS paste into a README	Classes, inline styles, odd nesting, and many tags without Markdown equivalents

LocalTools’ Markdown Studio:

Parses GitHub Flavored Markdown for live preview (sanitized HTML in the tab).
Exports copy HTML, download HTML, or copy rich text for apps that accept clipboard HTML.
Imports HTML from the clipboard (via a Turndown-style conversion) when you want Markdown back.

Treat import as a starting draft, not a byte-perfect reverse of export. Re-check headings, lists, and links after converting. For cleaning HTML snippets without converting to Markdown, use the HTML formatter & minifier and the fragment vs document guidance in formatting HTML snippets. For escaping when you author HTML by hand, see HTML entities.

A practical drafting workflow

Author in Markdown in the Markdown live editor—preview updates as you type; drafts can persist in local storage on your device only.
Use the toolbar for headings, lists, tasks, tables, and fenced code; turn on Auto-format when structure gets uneven.
Toggle Sync scroll and light/dark preview if you are matching a site theme.
When the destination needs markup: Copy HTML, Download HTML, or Copy as rich text.
If someone sent HTML: Import HTML from clipboard, then tidy Markdown and re-preview before committing.

For table-only cleanup inside a larger README, the Markdown table formatter is often faster than reformatting the whole document.

Common pitfalls

Writing HTML inside Markdown “just this once” — Raw HTML in Markdown is flavor- and sanitizer-dependent. Prefer Markdown constructs, or finish the piece as HTML.
Expecting Word HTML to become clean GFM — Round-trips leave noise; delete empty spans and fix lists by hand.
Assuming every renderer is GFM — Task lists and tables may not survive a stricter CommonMark pipeline.
Diffing exported HTML carelessly — Pretty-printed markup and fragment vs full document shape change the file; agree on export options first (text diffs).
Uploading proprietary drafts to online converters — Prefer local preview when the text is sensitive.

Choosing in practice

Situation	Prefer
README, CONTRIBUTING, PR / Issue body	Markdown (GFM)
Internal notes you will paste into Git later	Markdown
Newsletter / marketing email HTML	HTML (or Markdown → export once)
CMS field labeled “HTML”	Export HTML; optionally keep a `.md` source
Design-system component markup	HTML (or JSX), not Markdown
Quick check of a Markdown draft without uploads	Markdown live editor

You can keep both: Markdown as the editable source in the repo, HTML as a build or export step. Converting every draft to HTML “because the web uses HTML” usually adds friction without improving the writing.

Try it locally

Open the Markdown live editor:

Paste a short Markdown sample (heading, list, fenced code, optional table).
Skim the live preview; try Auto-format and sync scroll.
Export HTML or rich text, or import an HTML clipboard paste and inspect the Markdown result.

Processing stays in your browser; nothing is uploaded to LocalTools.