What is Markdown and how do you use it?

Short answer
Markdown is a lightweight plain-text formatting syntax that converts to HTML. Created by John Gruber in 2004, it lets you write formatted content using simple punctuation: # for headings, **bold**, *italic*, - for bullet lists, [link text](url) for links, and backticks for inline code. Markdown is the standard format for README files on GitHub, documentation sites, static site generators, and many CMS platforms including Notion, Ghost, and Obsidian.

Markdown was designed with one goal: make plain text readable and writable as-is, while also converting cleanly to HTML. A Markdown file is perfectly readable in a text editor even before it is rendered. This is in contrast to HTML, where the markup tags obscure the content when reading the raw source.

The core syntax covers most daily writing needs. Headings use one to six hash symbols (# H1, ## H2, ### H3). Emphasis uses asterisks or underscores: *italic* and **bold**. Unordered lists use hyphens or asterisks as bullet characters. Ordered lists use numbers followed by a period. Code blocks use triple backticks with an optional language identifier for syntax highlighting. Block quotes use a > prefix. Horizontal rules use three hyphens (---).

Multiple Markdown dialects have emerged because the original specification left some edge cases ambiguous. CommonMark is a rigorous standardised specification. GitHub Flavored Markdown (GFM) adds tables, task list checkboxes, and strikethrough. MultiMarkdown adds footnotes and citation support. Most modern Markdown editors and parsers support a superset of CommonMark.

Markdown's biggest limitation is that it does not handle complex layouts - multi-column sections, sidebars, and custom styling require either raw HTML embedded in the Markdown, or a templating layer on top. Platforms like MDX (Markdown + JSX) and AsciiDoc extend Markdown for these use cases.

For SEO, content written in Markdown and rendered to HTML is fully crawlable - search engines see the rendered HTML, not the Markdown source. A Markdown editor with a live preview panel lets you write and check formatting simultaneously without switching tools.

Try the tool

Markdown Editor →
Reviewed by Searchlight · Last reviewed