What Is Markdown? Lightweight Markup Explained
Markdown is a lightweight markup language created by John Gruber in 2004 that uses plain text formatting conventions to create structured documents. Markdown text is readable as-is and converts cleanly to HTML. It is the standard writing format for GitHub READMEs, documentation sites, static site generators, and technical writing.
Core Markdown Syntax
# Heading 1, ## Heading 2 (up to ######). **bold**, *italic*, ***bold italic***. [link text](URL). . `inline code`. Code blocks: indent 4 spaces or wrap in triple backticks (```). > blockquotes. - or * for unordered lists; 1. for ordered lists. --- for horizontal rules.
GitHub Flavored Markdown (GFM)
GFM extends basic Markdown with: fenced code blocks with syntax highlighting (```javascript), tables (| col | col |), task lists (- [x] done), strikethrough (~~text~~), @mentions, #issue-numbers, and emoji (:smile:). GFM is the most widely used Markdown variant due to GitHub's dominance in software development.
CommonMark and Markdown Parsers
Original Markdown had ambiguous edge cases that different parsers handled differently. CommonMark is a strict, unambiguous specification for Markdown adopted by GitHub, Reddit, Stack Overflow, and many documentation tools. When interoperability matters, choose a CommonMark-compliant parser.
Markdown vs RST vs AsciiDoc
reStructuredText (RST) is the standard for Python documentation (Sphinx). AsciiDoc is favored for technical book publishing (O'Reilly, Asciidoctor). Markdown has the largest ecosystem and easiest learning curve. For software documentation and technical blogs, Markdown is the pragmatic choice; for complex technical books with cross-references and semantic markup, AsciiDoc provides more power.