What is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. It lets you write formatted documents using plain text with minimal syntax — a hash for headings, asterisks for bold, hyphens for lists — and converts to clean HTML. Because Markdown files are plain text, they work perfectly with version control, can be edited in any text editor, and remain readable even without rendering. It has become the universal format for README files, developer documentation, static site generators, and note-taking applications.

CommonMark vs GitHub Flavoured Markdown

There is no single Markdown standard — different platforms implement slightly different extensions. The two most important variants are:

• CommonMark: A strict, unambiguous Markdown specification created in 2014 to resolve inconsistencies between implementations. Defines precise parsing rules for every edge case.
• GitHub Flavoured Markdown (GFM): GitHub's extension of CommonMark that adds tables, task lists (- [x]), strikethrough (~~text~~), autolinks, and fenced code blocks with syntax highlighting. GFM is the most widely used Markdown flavour for developer documentation.

Essential Markdown syntax reference

• Headings: # H1, ## H2, ### H3
• Bold: **text** or __text__
• Italic: *text* or _text_
• Inline code: `code`
• Code block: Three backticks, optionally followed by a language name for syntax highlighting
• Unordered list: Lines starting with -, *, or +
• Ordered list: Lines starting with 1., 2., etc.
• Link: [link text](https://url.com)
• Image: ![alt text](image.png)
• Blockquote: Lines starting with >
• Horizontal rule: Three or more hyphens --- on their own line
• Table (GFM): Pipe-separated columns with a header row separated by | --- |

How to use this tool

1. Type or paste Markdown text in the input editor.
2. Click Preview to render the HTML output.
3. View the rendered result in the preview panel.
4. The Generated HTML tab shows the underlying markup.
5. Copy the HTML to paste directly into a web page or CMS.

When to use Markdown vs HTML directly

Markdown is the right choice when content is written and maintained by humans — documentation, README files, blog posts, wikis. It is faster to write than HTML, easier to read in source form, and produces clean semantic HTML output. Use HTML directly when you need fine-grained layout control, custom attributes, or elements that Markdown cannot express. Many content platforms accept both: write in Markdown for text content and drop into HTML only where needed.