Markdown and HTML: Authoring vs. Rendering

Markdown is the authoring format; HTML is the rendering format. Most modern publishing pipelines move text between the two: write in Markdown, render to HTML for the browser, sometimes round-trip back to Markdown for migration or syndication. This previewer handles both directions in one panel with live preview.

Why Markdown for Authoring

The case for Markdown over rich-text editors (Microsoft Word, Google Docs) or WYSIWYG editors (TinyMCE, CKEditor):

• Plain text. Diffable in git, grep-able, sortable, scriptable.
• Portable. Works in any editor; no proprietary file format.
• Stable. Markdown source from 2014 still renders correctly today; rich-text formats break across versions.
• Fast to write. Once you know the syntax, faster than mousing through menus.
• AI-friendly. Most LLM training data includes Markdown; AI tools work better with Markdown input/output than rich text.

The case against:

• Limited expressiveness. No way to set arbitrary CSS, custom attributes, or complex layouts.
• Multiple flavors. CommonMark, GFM, MDX, kramdown, RDiscount, small differences cause portability issues.
• Learning curve. New writers need to memorize syntax.

For technical writing, blogging, documentation, README files, and structured content, the trade-offs favor Markdown. For visual layouts, marketing pages, and content that benefits from a designer's eye, rich HTML/CSS wins.

Why HTML for Rendering

HTML is what browsers actually render. Even Markdown content becomes HTML before display. So 'Markdown → HTML' is the standard direction; 'HTML → Markdown' is the migration direction.

The conversion direction matters:

• Markdown → HTML. Standardized (CommonMark spec). One Markdown source produces a deterministic HTML output.
• HTML → Markdown. Lossy. Many HTML constructs have no Markdown equivalent; tools make best-effort approximations.

Live Preview Workflow

Most Markdown editors offer a live preview pane:

• Type Markdown in the left panel.
• See rendered HTML in the right panel.
• Iterate fast, see exactly how a heading renders, a table aligns, a link displays.

This is faster than 'write, save, refresh, check' loops. Used heavily for:

• README drafting (preview how it'll look on GitHub).
• Blog post composition (see paragraph flow, heading hierarchy).
• Documentation writing (verify tables, code samples, lists render correctly).
• Email composition for Markdown-supporting platforms.

CommonMark vs. GFM vs. Other Flavors

The Markdown landscape is fragmented:

• CommonMark, the standardized spec. Conservative. Everything renders predictably.
• GitHub Flavored Markdown (GFM), CommonMark + tables, task lists, strikethrough, autolinks. The de facto modern standard.
• MDX, Markdown + embedded React components. Used by Docusaurus, Nextra, MDX-blog. Not portable to non-React tools.
• Markdown Extra, older extension with footnotes, definition lists, abbreviations.
• Pandoc Markdown, pandoc's superset, used for academic/print publishing. Most expressive but least portable.

This tool follows CommonMark + GFM, which covers ~95% of real-world Markdown use cases.

HTML to Markdown: The Reverse Conversion

The reverse conversion is the harder direction. HTML can express:

• Custom CSS classes (<div class="callout warning">), no Markdown equivalent.
• Inline styles (<span style="color:red">), no Markdown equivalent.
• Form elements (<input>, <button>), no Markdown equivalent.
• Semantic elements (<article>, <aside>), no Markdown equivalent.
• Arbitrary nesting (<div><div><span>...</span></div></div>), Markdown doesn't have div nesting.

Converters handle these by:

1. Mapping known elements. <h1> → #, <strong> → **, <a href="x"> → [text](x).
2. Dropping unsupported elements. <div class="..."> is unwrapped; the inner content is preserved.
3. Preserving raw HTML inline. Markdown allows raw HTML in the source, so the converter can keep complex HTML inline rather than dropping it. The Markdown still renders correctly.

The trade-off: aggressive mapping produces clean Markdown but loses fidelity; conservative mapping produces Markdown sprinkled with HTML fragments but preserves everything.

Migration Workflows

WordPress → Hugo/Astro/Eleventy. Export WordPress content as XML, parse HTML, run through HTML-to-Markdown, save as .md files in your static site generator's content directory. Manual cleanup needed for embedded shortcodes and unusual layouts.

Medium → personal site. Export Medium archive (HTML format), convert each post to Markdown, paste into your blog. Loses Medium-specific embeds; preserves text and structure.

Confluence → docs-as-code. Confluence export tools produce HTML; convert to Markdown for a docs-as-code workflow (writing in repos, reviewing via PR). Wiki-style internal links need manual rewriting.

Email → newsletter archive. Forward an email, copy the body, paste HTML, convert to Markdown for clean archive storage.

Markdown's Limitations and Workarounds

When pure Markdown isn't enough:

• Centered text. No native syntax; use <center> (deprecated but works) or raw HTML.
• Colored text. No native syntax; use raw HTML or rely on CSS classes via your renderer.
• Image with caption. No native syntax; many renderers accept ![alt](url "title") and convert title to caption.
• Footnotes. Some flavors support [^1]; CommonMark doesn't.
• Math equations. Not in CommonMark; KaTeX or MathJax adds it.
• Mermaid diagrams. Code blocks with mermaid lang tag rendered by Mermaid renderer downstream.

The escape hatch: raw HTML inside Markdown. Markdown spec allows it; modern renderers respect it (subject to security filtering).

Common Workflows

1. README authoring. Live preview while editing, push to GitHub when it looks right.
2. Blog drafting. Iterate in the previewer; export the rendered HTML to your CMS.
3. Migration. Paste HTML extracted from old CMS; get Markdown for new system.
4. Email cleanup. Paste HTML from email; get clean Markdown for archival.
5. AI workflow input. Convert your existing HTML notes to Markdown for feeding into LLM context windows.

Privacy

Markdown parsing and HTML rendering both run in your browser. Round-tripping is purely local. Drafts and internal docs stay in your tab.