What Markdown is actually for
John Gruber created Markdown in 2004 with a specific goal: to let writers write in plain text that reads naturally and then convert it to valid HTML. The design principle was that a Markdown file should be readable as-is, without rendering — unlike HTML, which is littered with angle brackets that interrupt reading.
Markdown uses simple conventions: `**bold**` for bold, `# Heading` for headings, `[link text](url)` for links, `- item` for lists. These look natural in a plain text file and convert predictably to HTML.
Where Markdown thrives: README files (GitHub uses it extensively), documentation, blog posts, notes, and any context where a writer wants to focus on content rather than markup. Most static site generators, documentation tools, and note-taking apps use Markdown as their native format.
What HTML is actually for
HTML (HyperText Markup Language) is the language of the web. It's what browsers read. Unlike Markdown, it has a formal specification, supports hundreds of elements, and handles semantic structure, accessibility attributes, embedded media, forms, and interactive elements.
HTML is the right tool when you need precise control over structure, when you're building something for a browser, when you need attributes (like `class`, `id`, `aria-label`), or when you're generating content programmatically.
HTML is not a great format for human writing. Nobody sits down to write a blog post in raw HTML. That's what Markdown and content management systems are for.
How Markdown converts to HTML
Markdown converters (often called parsers) read Markdown syntax and output equivalent HTML. A `# Heading` becomes `<h1>Heading</h1>`. `**bold**` becomes `<strong>bold</strong>`. A paragraph becomes a `<p>` element.
The Markdown to HTML tool on Irreva shows this conversion live — you type Markdown on the left and see the rendered HTML on the right. It uses a standards-compliant Markdown parser and supports GitHub Flavored Markdown (GFM), which adds tables, strikethrough, and task lists to the basic syntax.
Markdown flavors and why they matter
The original Markdown spec left many edge cases ambiguous. Over the years, different platforms implemented it differently and added extensions. GitHub Flavored Markdown (GFM) is now the most widely used variant, largely because of GitHub's dominance in the developer world.
CommonMark is an attempt to standardize Markdown with a precise specification. It resolves the ambiguities in the original spec and is implemented consistently across tools.
For practical purposes: if you're writing README files or documentation for GitHub, use GFM. If you're using a static site generator, check which flavor it supports. For general writing, the differences rarely matter.