Markdown is a lightweight markup language created by John Gruber in 2004 with the goal of being readable in its raw form while still producing valid HTML when processed. In Markdown, formatting is expressed through simple punctuation: a # at the start of a line creates a heading, wrapping text in **asterisks** makes it bold, and surrounding text with backticks creates inline code. The raw text is intentionally readable as-is, without needing to be rendered.
Core Markdown syntax
The most commonly used Markdown elements are:
# Heading 1 ## Heading 2 **bold text** *italic text* `inline code` - Unordered list item 1. Ordered list item [Link text](https://example.com)  > Blockquote ``` code block ```
These nine elements cover around 95% of what most people need for everyday documentation and writing.
Why developers prefer Markdown
Plain text portability. Markdown files are just .txt with a .md extension. They can be read in any text editor without special software, version-controlled in Git without binary diffs, and processed by any Markdown renderer.
Speed. Formatting a document in a rich-text editor requires mouse clicks and menu navigation. In Markdown, you never leave the keyboard: type ** before and after a word to bold it, or ## at the start of a line to create a heading. Experienced Markdown writers format as fast as they type.
Universal tooling. GitHub, GitLab, Notion, Obsidian, VS Code, Jupyter notebooks, Slack, Discord, Reddit, and Stack Overflow all render Markdown. Write once, display correctly everywhere.
Markdown flavors and extensions
The original Markdown specification was intentionally minimal and left some behaviors undefined, which led to different implementations handling edge cases inconsistently. CommonMark, published in 2014, is a fully specified standard that resolves these ambiguities and is now the implementation most modern tools follow.
GitHub Flavored Markdown (GFM) extends CommonMark with tables, strikethrough (~~text~~), task lists (- [x] done), and fenced code blocks with syntax highlighting. Most documentation tools and note-taking apps support a GFM-like superset.
Where Markdown is used
- READMEs and documentation. GitHub renders
README.mdfiles automatically on repository pages. All major open-source projects write their documentation in Markdown. - Static site generators. Hugo, Jekyll, Gatsby, Eleventy, and Astro all use Markdown as their content format — write in Markdown, render as HTML.
- Note-taking apps. Obsidian, Notion, Bear, and Typora store notes as Markdown files, giving you plain-text portability with rich formatting on display.
- Technical writing platforms. GitBook, MkDocs, and Docusaurus build entire documentation sites from directories of Markdown files.
When not to use Markdown
Markdown has limitations. It has no standardized way to add color, complex table layouts, footnotes (outside of extensions), or custom HTML attributes. For highly structured documents requiring complex layout — annual reports, legal briefs, multi-column layouts — rich-text formats, LaTeX, or HTML are more appropriate. For collaborative editing with non-technical team members who are unfamiliar with syntax, a WYSIWYG tool like Google Docs may cause less friction.