HTML is a markup language for browsers. Markdown is shorthand for writing HTML without typing tags. John Gruber designed markdown in 2004 to look like plain email: readable as-is, not just when rendered. Both formats produce formatted content on the web, but they're built for different hands.
What each one is
HTML is the native language of browsers. Every heading, paragraph, and link on the web is ultimately an HTML element with angle-bracket tags and attribute syntax. Browsers render HTML directly with no preprocessing step. Developers and design tools produce it constantly.
Markdown is a formatting convention, not a browser language. It needs a parser (something like marked, pandoc, or next-mdx-remote) to convert .md files into HTML before (or while) serving them. The markdown syntax you write in a README or blog post never reaches the browser directly.
The key difference: who writes it
HTML is for developers and tools. It's precise, verbose, and has a 300-page spec behind it. Writing HTML by hand is normal in component code but tedious for prose.
Markdown is for writers. The syntax is fast to type, readable as plain text, and handles the formatting needs of 90% of written content: headings, lists, links, code, tables, blockquotes. You do not need to know what <strong> means to make something bold.
What markdown can do (and can't)
Markdown handles everything a blog post, README, or documentation page needs:
- Headings (
#,##,###) - Bold and italic (
**bold**,*italic*) - Links and images (
[text](url),) - Ordered and unordered lists
- Blockquotes and horizontal rules
- Fenced code blocks with language syntax hints
- Tables (GitHub Flavored Markdown / GFM)
- Task lists (
- [ ]and- [x])
What markdown cannot do:
- Apply custom CSS classes to elements
- Build complex page layouts (grids, sidebars, multi-column)
- Render form elements (
<input>,<select>,<textarea>) - Embed interactive components or scripts
- Inline SVG or canvas elements
- Control specific HTML attributes (
data-*,aria-*,role,tabindex)
Any output that needs precise control over HTML structure or attributes requires raw HTML.
When to write markdown
Use markdown when:
- Writing blog posts, documentation, or READMEs
- Storing content in Git (markdown diffs cleanly and merges well)
- Non-developers need to edit the content
- The content will be converted to multiple output formats (HTML, PDF, ePub)
- Portability matters (markdown files open in any text editor, any OS, any decade)
If you want to see how your markdown renders, write markdown online and preview it instantly.
When to write HTML
Use HTML when:
- Building email templates (email clients ignore CSS in ways markdown parsers don't account for)
- Creating complex landing pages with custom layout and component structure
- You need specific CSS classes,
data-*attributes, or ARIA roles on elements - The output includes forms, interactive widgets, or embedded scripts
- Working inside a component framework where the output is already HTML
When to mix both (MDX)
MDX is markdown with JSX support. It lets you write markdown and drop <ComponentName /> anywhere inline or between paragraphs. It's the standard format for React and Next.js documentation sites.
Use MDX when:
- Your site uses React or Next.js and you want components inside content
- Documentation pages need live code demos, interactive examples, or custom callouts
- Markdown covers 80% of the page but you need one or two custom components for the rest
MDX compiles to JavaScript, not raw HTML, so it requires a build step. For static content that doesn't need React components, plain markdown compiled to HTML is simpler and faster.
The conversion path
Markdown compiles to HTML. You can convert markdown to HTML with a single step, and the output is clean semantic markup. Going the other direction is messier. HTML-to-markdown converters handle simple cases well but struggle with deeply nested elements, inline styles, or non-semantic markup.
If you're moving content from a legacy HTML CMS to a markdown-based system, expect to clean up the converted output manually.
Quick reference
| Situation | Use | |-----------|-----| | Blog post | Markdown | | Documentation | Markdown | | README | Markdown | | Stored in Git | Markdown | | Email template | HTML | | Landing page | HTML | | Form | HTML | | Inline component in content | MDX | | React/Next.js content page | MDX | | Visual editor output | HTML (often) |
The short answer
Write markdown when a human is writing prose content that will be stored, versioned, or shared. Write HTML when a tool or developer is building page structure that needs precise attribute control. Use MDX when you need both in the same file.
For most documentation and content workflows, markdown is the right default. You can always drop down to raw HTML inside a markdown file when you need it; most parsers allow inline HTML blocks. Start with markdown and reach for HTML only where markdown falls short.
Write markdown and preview it at md0.io with the online markdown editor. Need the exact syntax? Use the markdown cheatsheet as a reference. To convert an existing file, try the markdown to HTML converter or HTML to markdown converter.