Everything you need to know about MD
Markdown (.md) is John Gruber's lightweight markup language from 2004 - a way to write formatted text that converts cleanly to HTML. The brilliance: the source itself is readable, even without rendering. Markdown is the lingua franca of READMEs, documentation sites, static blogs, and modern note-taking apps.
How it works under the hood
- Plain text first. A Markdown file is human-readable as-is. `# Header` is a header in Markdown AND looks like a header in plain text.
- CommonMark vs flavors. Original Markdown was loosely specified. CommonMark (2014) is the strict standard. GitHub-Flavored Markdown (GFM) adds tables, task lists, strikethrough.
- Inline HTML allowed. When Markdown isn't enough, drop in raw HTML - parsers preserve it. Useful for rare cases like complex tables.
- Code blocks with fences. Triple backticks (```) start a code block. Specify language for syntax highlighting: ```python.
Where you'll actually use it
- GitHub READMEs and project documentation
- Static site generators (Jekyll, Hugo, Astro, Next.js)
- Technical blog posts
- Note-taking (Obsidian, Notion, Bear all use Markdown)
How it compares to alternatives
MD vs HTML: MD is faster to write; HTML has more layout control. MD vs reStructuredText (RST): RST has stronger doc tooling (Sphinx); MD has bigger ecosystem. MD vs MDX: MDX adds JSX components to MD - JSX in your prose.
Things that will trip you up
- Different parsers render the same MD differently - especially for edge cases like nested lists in tables
- GFM tables don't allow newlines in cells - use HTML tables for rich content
- Linking to anchors requires kebab-case slugs derived from headers - test before publishing
Test it yourself: Any Markdown editor (VS Code preview, Typora, iA Writer), markdownlint for linting, Pandoc for conversion to other formats.