Markdown vs HTML vs RTF — picking a lightweight document format
Compare Markdown, HTML, and RTF for READMEs, meeting notes, email drafts, and Word handoffs by portability, expressiveness, tooling, and how the recipient renders it.
Four axes that drive the decision
Markdown, HTML, and RTF all do “text plus formatting”, but their design intent is very different. Four axes carry most of the weight. Portability decides whether the document survives being copied between editors, operating systems, or environments. Expressiveness is how far the format goes — tables, embedded images, styling, embedded scripts. Editing tools separate “any text editor works” from “you need a specific app”. Render target matters because GitHub, Slack, Word, and email clients all interpret the same file differently.
Picking by default (“just Markdown” or “just HTML”) is where most mismatches come from. The cleaner habit is to start from the render target. A technical blog post wants Markdown, a corporate newsletter wants HTML, and a deliverable for a Word-driven client wants RTF — the fit is usually obvious once you frame it that way.
Side-by-side comparison
| Property | Markdown | HTML | RTF |
|---|---|---|---|
| Formatting style | Lightweight syntax (# h1, **bold**) | Tags + CSS (<h1>, <p>, <a>) | Control words (\b, \par, \fs24) |
| Standard spec | CommonMark (2014) / GFM | W3C HTML Living Standard | Microsoft RTF Specification 1.9.1 (frozen since 2008) |
| Year introduced | 2004 (John Gruber) | 1993 (Tim Berners-Lee) | 1987 (Microsoft) |
| Editing software | Any text editor | Text editor / IDE | Word / TextEdit / Pages / WordPad |
| Word compatibility | Limited (paste loses formatting) | Limited (paste works; fidelity varies) | Excellent (Word’s native interchange format) |
| GitHub display | Excellent (README rendered automatically) | Raw display (not rendered) | Not supported |
| Email attachment | Often unreadable on the receiving side | HTML mail; client variance is significant | Standard in Outlook / older mail clients |
| Images | External link reference | External link or Base64 embed | Binary embedding supported |
| File size | Smallest (plain text) | Medium (tag overhead) | Largest (control words + embedded images) |
One-line summaries to make the rows concrete. Markdown is interpreted by GitHub, Notion, Slack, Discord, and most static-site generators, but flavours diverge across engines (CommonMark, GFM, kramdown, Pandoc). HTML is the most expressive option when the render target is a browser, but HTML email faces a long tail of client-specific quirks (Gmail, Outlook, Apple Mail) and not all CSS features are supported. RTF is Word’s plain-text interchange format — formatting is stored as backslash-prefixed control words inside an ASCII file, and TextEdit, Pages, Word, WordPad, and LibreOffice can all read it.
Use case → recommended format
README files, technical blogs, OSS documentation: Markdown, every time. GitHub, GitLab, Bitbucket, Notion, and dev-focused publishing platforms all render it natively. Learning GitHub Flavored Markdown (tables, task lists, fenced code blocks with syntax highlighting) covers about 80 % of real-world needs.
Marketing site, landing page, web app: HTML + CSS. Structural elements (<article>, <nav>, <header>), JavaScript integration, and responsive layout all assume HTML. The modern pattern is to author in Markdown / MDX and let the build step (Astro, Next.js, Docusaurus) emit HTML.
Newsletters and marketing email: HTML email, but be prepared for legacy techniques — inline CSS, table-based layout, Outlook-specific VML, conditional comments. Dedicated tools (Stripo, MJML) earn their place by abstracting these away.
Deliverables for Word-driven clients, legal or government documents: RTF is the safer bet. Word’s .docx (Office Open XML) has higher fidelity but breaks across versions occasionally; RTF is frozen but reliably round-trips between editors as a compatibility baseline.
API documentation, OpenAPI, Swagger UI: Markdown. The OpenAPI description field accepts Markdown, and Swagger UI, Redoc, and Stoplight all render CommonMark.
Browser-only conversion / pitfalls
Markdown ↔ HTML round-trips fit cleanly inside the browser. markdown-html-convert converts both directions, supporting CommonMark plus GFM tables and task lists. To see the result while you write, markdown-preview offers live preview, and for long documents markdown-toc extracts the heading hierarchy and emits a Markdown table of contents with anchor links.
Three pitfalls catch teams in practice. First, Markdown flavour drift: GFM task lists (- [ ]) and footnotes ([^1]) are not in CommonMark, so some engines pass them through unrendered. Confirm the target engine before relying on a feature. Second, CSS support in HTML email: flexbox, grid, and most pseudo-classes are not honoured by major mail clients, so table layout plus inline CSS remains the realistic baseline (with mso- prefixes and conditional comments for Outlook). Third, RTF character encoding: older RTF assumes CP1252 or Shift_JIS for control words, which can mojibake on cross-language exchange. For reliable Unicode, use newer RTF with \u escapes or migrate to .docx. The implementation is auditable on GitHub, and the DevTools Network tab makes it easy to confirm that documents never leave the page during conversion.