Markdown vs HTML vs Rich Text: A 2026 Writer's Format Guide

Three formats dominate how text gets written and stored online: Markdown (plain text with light syntax), HTML (full structural markup), and rich text (visual WYSIWYG editors like Google Docs, Notion, Word). Each has a job. Each is misused in places where one of the others would be better.

This guide is the working writer's reference for 2026 — when to pick which format, the conversion gotchas between them (the part that breaks portability), the Markdown variants you should know (CommonMark, GFM, MDX, MyST), and the practical workflow that lets you write once and publish anywhere.

The three formats compared

Markdown

Plain text with light symbols for formatting:

# Heading
This is **bold** and this is *italic*.
- Bullet point
- Another bullet

[Link text](https://example.com)

Why use it: portable (just text), version-controllable in Git, fast to type once you know syntax, renders consistently across platforms that support it, future-proof.

Why avoid it: limited formatting (no tables in original spec, no nested complexity), no rich media inline beyond images, plain text appearance scares non-technical writers.

HTML

Full structural markup:

<h1>Heading</h1>
<p>This is <strong>bold</strong> and this is <em>italic</em>.</p>
<ul>
  <li>Bullet point</li>
  <li>Another bullet</li>
</ul>
<a href="https://example.com">Link text</a>

Why use it: full control over structure, styling, semantic meaning. Universal browser support.

Why avoid it: verbose, intimidating for non-developers, easy to mess up nesting, mixing content with presentation is anti-pattern.

Rich Text (WYSIWYG)

Editors like Google Docs, Notion, Word, ContentEditable-based web editors. You see formatting visually; the underlying format varies (often a proprietary XML, sometimes HTML, sometimes a JSON tree).

Why use it: zero learning curve, immediate visual feedback, comfortable for non-technical writers, supports embedded media and complex layouts.

Why avoid it: storage format usually proprietary or hard to export cleanly, version control via Git is painful, copy-paste between rich text systems often produces messy markup, hard to bulk-edit programmatically.

When to use which

A simple decision flow:

Use Markdown when:

Writing for a developer audience (READMEs, technical docs, blog posts on static-site generators).
Documentation that needs to live in Git alongside code.
Long-form content where you want focus over visual fiddling.
Notes-to-self and personal knowledge management (Obsidian, Logseq, plain files).
Content that will be processed programmatically (LLM training data, content APIs).

Use HTML when:

Writing for a specific website that needs custom styling beyond Markdown's defaults.
Email templates (needs inline styles, table layouts for legacy clients).
Embedding interactive elements (forms, custom components).
Content with truly complex structure (multi-column layouts, sidebars).

Use Rich Text when:

Collaborative editing with non-technical co-writers (Google Docs is hard to beat).
Content with heavy formatting needs (annual reports, presentations, contracts).
Quick informal communication (Notion pages, internal wikis).
Audiences expecting WYSIWYG editing without learning syntax.

The Markdown variants matter

"Markdown" isn't one spec. There are at least seven important variants:

CommonMark (2014)

The standardised version of Markdown. Solves ambiguities in the original 2004 Markdown by John Gruber. Use this as your baseline.

GitHub Flavored Markdown (GFM)

CommonMark + extensions for:

Tables
Strikethrough (~~text~~)
Task lists (- [ ] todo)
Auto-linked URLs
Code blocks with syntax highlighting

Powers GitHub, GitLab, Bitbucket, most modern dev tools. Use this for technical writing.

MDX

Markdown + JSX. Embeds React components inside Markdown:

# My post

<CustomChart data={salesData} />

Regular Markdown continues here.

Used by Next.js, Docusaurus, Gatsby for component-rich blogs. Use this when you need interactive React components alongside written content.

MyST (Markedly Structured Text)

Scientific publishing variant. Adds directives for citations, equations, cross-references, custom blocks. Used by Jupyter Book and academic publishing platforms.

Pandoc Markdown

Pandoc-specific extensions for academic writing — definition lists, footnotes, citations from BibTeX, complex tables. Use this when converting between many formats (Markdown → Word, LaTeX, PDF, EPUB).

Multi-Markdown

Extends Markdown for academic writing with footnotes, citations, math. Used in some scientific contexts.

Notion Markdown / Obsidian Markdown / Slack Markdown

Each tool's flavour with quirks. Notion's [[wiki-links]], Obsidian's ![[embed]], Slack's *single-asterisk for bold* — all "Markdown" but mutually incompatible.

Practical advice: pick CommonMark as baseline, GFM as the de facto standard, and only adopt tool-specific extensions when you commit to that tool ecosystem.

Conversion gotchas

The promise of Markdown is portability — write once, render anywhere. Reality is messier.

Markdown → HTML

Mostly clean conversion via Markdown parsers (marked, markdown-it, Pandoc). Gotchas:

Raw HTML inside Markdown sometimes gets escaped (security feature) — set parser options if you need raw HTML pass-through.
Tables don't exist in original Markdown; GFM tables convert to HTML tables but rendering depends on CSS.
Code blocks need syntax highlighting library separately (Prism, Highlight.js, Shiki).

Markdown → Word (.docx)

Pandoc handles this well. Gotchas:

Style mapping (your "Heading 2" needs to match Word's "Heading 2" style for outline view).
Images embedded vs linked.
Footnotes work but cross-references can break.

HTML → Markdown

Lossy by design — HTML has more expressivity than Markdown. Tools like Turndown (used in HTML to Markdown) make sensible choices but:

<div> with custom classes loses meaning.
Inline styles disappear.
Tables convert but cell alignment can drift.
Embedded media often turns into bare links.

Rich Text (Word/Google Docs) → Markdown

Most painful conversion in 2026. Approach:

Export from Word/Docs as .docx.
Run through Pandoc: pandoc input.docx -o output.md --wrap=preserve.
Hand-fix the output (footnotes, images, tables typically need cleanup).

For Google Docs specifically, the "Docs to Markdown" Chrome extension does a reasonable job. Notion's built-in "Export as Markdown" is clean.

Notion → Markdown

Notion has built-in export. Issues:

Internal wiki links [[page]] don't translate to external Markdown.
Embedded databases export as static tables (lose interactivity).
Cover images and emoji icons get separated from page.

Tooling for Markdown work

Editors

VS Code with Markdown All in One extension: best for technical/developer use, preview pane, snippet support.
Obsidian: knowledge management focus, wiki-style linking, plugin ecosystem.
Typora / iA Writer / Bear: distraction-free, native-feeling apps.
GitHub web editor: rendering matches what others will see.
Browser Markdown editor: quick edits without installing anything.

Linters / formatters

markdownlint (Node, CLI): catches common issues (mixed list styles, heading skip levels).
Prettier: opinionated formatting, ensures consistent style across team.

Static site generators that consume Markdown

Hugo (Go): fast, single binary.
Jekyll (Ruby): GitHub Pages default.
Astro (JS): modern, framework-agnostic.
Next.js + MDX: React-based, full power of components.
Docusaurus: documentation sites.
MkDocs / Material for MkDocs: Python ecosystem, beautiful defaults.

Markdown best practices

Patterns that age well:

One sentence per line (semantic line breaks). Looks weird in source but git diffs become readable — each changed sentence is a separate diff line.
Consistent heading levels. Skip levels (h2 directly to h4) breaks accessibility and outline tools. Always go h1 → h2 → h3 in sequence.
Reference-style links for long URLs:

Read the [official spec][cmark-spec] for details.

[cmark-spec]: https://spec.commonmark.org/

Keeps prose clean. URLs grouped at end of doc.

Front-matter for metadata:

---
title: Post title
date: 2026-05-31
tags: [markdown, writing]
---

# Post title

Content here...

Most SSGs (Hugo, Jekyll, Next.js, Astro) parse YAML front-matter.

Use code fences with language hints for syntax highlighting:

\`\`\`javascript
const x = 1;
\`\`\`

Not \``` alone — language hints matter for accessibility and rendering.

When NOT to use Markdown

Common over-application:

Email templates: HTML is necessary (inline styles, table layouts for Outlook). Markdown→HTML conversion loses email-client robustness.
Marketing landing pages: need design fidelity beyond Markdown defaults. Use HTML + CSS or a visual builder.
Legal documents: precise formatting matters; Word/PDF wins.
Designed reports (annual reports, pitch decks): visual tools (Figma, Canva, Notion, Word) win.
Anything with complex multi-column layouts: Markdown wasn't designed for this.

For everything text-heavy where structure matters more than visual fiddling, Markdown remains the right default in 2026.

The migration path

If you're moving content between tools:

From Word/Docs → Markdown for Git/blogs: Pandoc + manual cleanup. Budget 5-10 minutes per article.
From Notion → Static site: Notion export → MDX → site. Plugin ecosystems (notion-to-md, super.so) exist.
From WordPress → Markdown: WP-to-Markdown export plugin, then hand-cleanup. Or REST API + custom script for bulk.
From legacy HTML → Markdown: Turndown library or HTML to Markdown.
From Markdown → publishing: pick an SSG, point at your Markdown directory, customize theme.

The migration cost is one-time. The portability win is forever.

Common Markdown mistakes

After reviewing thousands of Markdown docs:

Skipping heading levels. Use sequential h1 → h2 → h3.
Mixing list styles (* vs - vs +). Pick one, stick with it.
Using HTML when Markdown suffices. <b>bold</b> works but **bold** is the right choice.
Inconsistent emphasis style (*italic* vs _italic_). Pick one, configure prettier to enforce.
Hard wrap at 80 chars vs sentence-per-line. Pick a convention and stick with it across the codebase.
Code blocks without language hints. Always specify the language for syntax highlighting.
Bare URLs without descriptive link text. Bad for accessibility and SEO.
Forgetting front-matter. SSGs need it; sharing without is missing metadata.

Tools to use

Markdown Editor — split-pane editor with live preview, syntax highlighting.
Markdown to HTML — convert Markdown to clean HTML.
HTML to Markdown — convert legacy HTML to Markdown for portability.
Text Formatter — clean up messy text before converting to Markdown.

The bottom line

Three formats. Three jobs.

Markdown for portable, version-controlled, long-form writing — especially when developers are involved. Default to GFM as the practical standard. Use CommonMark when you need strict compatibility.

HTML when you need full control: email templates, custom landing pages, embedded interactivity.

Rich Text (Google Docs, Word, Notion) for collaborative drafting with non-technical co-writers and content with heavy formatting needs.

The skill is recognising which format the task requires — and accepting the lossy conversion when you need to move between them. Plan content workflows so each piece lives in its right format from the start. Retrofitting is expensive.

For most working writers and developers in 2026: spend an afternoon learning GFM Markdown properly, set up a Markdown editor in your workflow, and watch how many "where is my content?" problems quietly disappear.