Overview
Markdown is a lightweight markup language that uses simple, intuitive plain-text formatting syntax to create structured documents that can be converted to HTML and other formats. Created by John Gruber with contributions from Aaron Swartz, Markdown's design philosophy is that the source text should be readable as-is, without any rendering — a heading is a line prefixed with # characters, emphasis is text wrapped in asterisks, a link is text in brackets followed by a URL in parentheses, and a list is lines prefixed with dashes or numbers.
This readability-first approach has made Markdown the dominant format for writing on the modern internet. GitHub uses Markdown for README files, issues, pull requests, and wikis. Stack Overflow, Reddit, Discord, Slack, Notion, Obsidian, and countless other platforms support Markdown for user-generated content. Static site generators like Jekyll, Hugo, Gatsby, and Astro use Markdown files as their content source. Documentation platforms (MkDocs, Docusaurus, VuePress, GitBook) are built entirely around Markdown authoring.
Markdown's appeal extends beyond developers. Technical writers, bloggers, academics, and note-takers use Markdown because it lets them focus on content without the distraction of formatting toolbars or the complexity of HTML. The format is inherently future-proof — Markdown files are plain text that will remain readable on any system for decades, regardless of which applications come and go.
History
John Gruber published the original Markdown specification and a Perl conversion script on his blog, Daring Fireball, on March 19, 2004. The original specification was deliberately informal and left many edge cases ambiguous, leading to divergent implementations as Markdown's popularity grew. Different parsers (PHP Markdown Extra, MultiMarkdown, GitHub Flavored Markdown, Pandoc, and others) each added their own extensions and resolved ambiguities differently.
In 2012, Jeff Atwood and John MacFarlane initiated the CommonMark project to create an unambiguous, comprehensive specification with a reference implementation and test suite. CommonMark 0.30 (published in 2021) defines precise parsing rules for every edge case. GitHub Flavored Markdown (GFM), specified by GitHub, extends CommonMark with tables, task lists, strikethrough, and autolinks. Despite the proliferation of variants, the core syntax (headings, emphasis, links, images, code blocks, lists, blockquotes) is consistent across all major implementations.
Technical Details
Markdown syntax maps directly to HTML elements. Headings use 1-6 hash characters (# = h1, ## = h2, etc.), paragraphs are separated by blank lines, emphasis uses single asterisks or underscores (*italic* or _italic_), strong emphasis uses double (**bold**), code spans use backticks (`code`), and fenced code blocks use triple backticks with an optional language identifier for syntax highlighting. Links use [text](url) and images use . Unordered lists use -, *, or + prefixes, and ordered lists use numbers followed by periods.
CommonMark parsing operates in two phases: first, the document is divided into blocks (paragraphs, headings, code blocks, lists, blockquotes, thematic breaks) based on indentation and marker patterns; second, inline content within blocks is parsed for emphasis, links, code spans, and other inline elements using a delimiter-matching algorithm. GFM adds table syntax using pipe (|) characters and hyphens for column alignment, task list items ([x] and [ ] checkboxes), strikethrough with double tildes (~~text~~), and automatic URL detection. Extended syntax in platforms like Obsidian adds features like wikilinks ([[page]]), callouts, and embeds.
Pros & Cons
Pros
- Source text is readable without any rendering — formatting is intuitive plain text
- Ubiquitous support across development platforms, documentation tools, and note-taking apps
- Plain text files are future-proof, version-control friendly, and universally portable
- Converts to HTML, PDF, DOCX, and many other output formats via tools like Pandoc
- Low learning curve — basic syntax can be learned in minutes
Cons
- No standardized extended syntax — tables, footnotes, and math vary by implementation
- Limited formatting capabilities compared to HTML or DOCX (no columns, page layout, colors)
- Original specification is ambiguous, leading to rendering differences between parsers
- No native support for metadata (YAML front matter is a convention, not part of the spec)
- Complex layouts and interactive content require falling back to embedded HTML
Common Use Cases
- Writing README files, documentation, and wikis on GitHub and GitLab
- Authoring blog posts and content for static site generators (Hugo, Jekyll, Astro)
- Taking structured notes in knowledge management tools like Obsidian and Notion
- Writing technical documentation with MkDocs, Docusaurus, or GitBook
- Formatting messages in developer communication platforms (Slack, Discord, Teams)
- Drafting academic papers and converting them to multiple output formats with Pandoc