What Is Markdown? A Complete Explanation of the Lightweight Markup Language
Quick Answer
Markdown is a plain text markup language that uses simple symbols to format text: # for headings, ** for bold, * for italic, - for lists, [text](url) for links. It is designed to be readable as plain text and convertible to HTML. Use our free Markdown to HTML Converter to render Markdown in your browser.
Introduction
Markdown is a lightweight markup language created by John Gruber in 2004 that uses plain text formatting to produce structured documents. The goal is readability — Markdown source text should look like what it represents, without the visual clutter of HTML tags. Markdown is the standard for README files on GitHub, documentation sites, blog posts, comments on platforms like Reddit and Stack Overflow, and note-taking apps like Obsidian and Notion. Markdown converts to HTML for web publishing.
Step by Step
-
Learn the basic syntax
Headings: # H1, ## H2, ### H3. Bold: **text**. Italic: *text*. Lists: - item or 1. item. Links: [text](url). Images: . Code: `inline` or ```block```. Blockquotes: > quote. Horizontal rule: ---.
-
Understand the philosophy
Markdown is designed to be readable as plain text. The source should look close to the final rendered output — **bold** looks like bold, # Heading looks like a heading. This contrasts with HTML, where <strong>bold</strong> and <h1>Heading</h1> are visually cluttered.
-
Learn the variants
Original Markdown (Gruber's spec) is minimal. CommonMark is a standardized, well-specified version. GitHub Flavored Markdown (GFM) adds tables, strikethrough, task lists, and autolinks. MDX lets you embed React components in Markdown. Most tools support GFM.
-
Convert Markdown to HTML
Markdown is converted to HTML for web publishing. # Hello becomes <h1>Hello</h1>, **bold** becomes <strong>bold</strong>. Static site generators (Astro, Hugo, Jekyll) convert Markdown at build time. Use our Markdown to HTML Converter for instant conversion.
Examples
Heading and paragraph
Input: # Title
A paragraph.
Output: <h1>Title</h1>
<p>A paragraph.</p>
Bold and italic
Input: **bold** and *italic*
Output: <strong>bold</strong> and <em>italic</em>
Link and image
Input: [text](https://example.com) and 
Output: <a href="https://example.com">text</a> and <img src="image.png" alt="alt">
Common Problems
- Line breaks —a single newline in Markdown does not create a line break in HTML. Use two spaces at the end of a line, or two newlines for a paragraph break.
- Nested lists —indentation matters. Use 2 or 4 spaces consistently for nested items; mixing them can break the list structure.
- Raw HTML —most Markdown parsers pass through raw HTML, but some sanitize it. Check your parser's behavior if you embed HTML directly.
- Different flavors —Original Markdown, CommonMark, and GFM have subtle differences. Check which flavor your target platform supports.
Tips
- Use Markdown for writing and documentation —it is much easier to read and write than HTML.
- GitHub Flavored Markdown (GFM) is the most common variant —it adds tables, strikethrough, and task lists.
- Write in Markdown and convert to HTML at build time for blogs and documentation sites.
- Use our Markdown to HTML Converter to render Markdown instantly in your browser.