Why Markdown Became the Developer's Default Format
Markdown is a lightweight markup language that uses plain text conventions to represent formatted content. Created by John Gruber in 2004 with input from Aaron Swartz, it was designed to be readable as plain text while converting cleanly to HTML. Its simplicity and readability have made it the dominant format for documentation, READMEs, blog posts, technical notes, and chat messages across the developer ecosystem.
The format's popularity stems from a rare combination of properties. It is plain text, so it works with any editor and diffs cleanly in version control. It is human-readable even without rendering, so you can scan a Markdown file and understand its structure at a glance. It maps to HTML, so it renders to rich content on the web. And it is concise, letting you express formatting with a few characters rather than verbose tags.
Today, Markdown is everywhere: GitHub READMEs, documentation sites (MkDocs, Docusaurus, VuePress), static site generators (Jekyll, Hugo, Eleventy), note-taking apps (Obsidian, Notion, Bear), chat platforms (Slack, Discord, GitHub Comments), and even LLM prompts and responses. Knowing Markdown well is a baseline literacy for modern software development.
- Created in 2004 by John Gruber with input from Aaron Swartz
- Plain text, readable without rendering, diffs cleanly in version control
- Maps to HTML for rich rendering on the web
- Used in READMEs, docs, blog posts, notes, chat, and LLM prompts
Core Markdown Syntax
Markdown's core syntax covers the most common formatting needs with a small set of conventions. Headings use `#` characters (one for H1, two for H2, and so on). Paragraphs are separated by blank lines. Bold text uses `**double asterisks**` or `__double underscores__`, and italic text uses `*single asterisks*` or `_single underscores_`.
Lists are equally simple: ordered lists use numbers followed by periods, and unordered lists use `-`, `*`, or `+`. Nest lists by indenting child items by two or four spaces (be consistent within a document). Code can be inline, wrapped in single backticks, or in a fenced block wrapped in triple backticks. Fenced code blocks can specify a language for syntax highlighting, which most renderers support.
Links use the format `[text](URL)`, and images use ``. Blockquotes use `>` at the start of a line. Horizontal rules use three or more `---`, `***`, or `___` on a line. These basic constructs cover perhaps 95% of what you need in typical documentation, and learning them well pays dividends every day.
- Headings: # for H1 through ###### for H6
- Bold: **text** — Italic: *text* — Code: `code`
- Lists: - or * for unordered, 1. for ordered
- Links: [text](URL) — Images: 
- Code blocks: triple backticks with optional language for highlighting
Markdown Flavors and Extensions
While Gruber's original Markdown specification was minimal, the format has been extended in many directions over the years. Different tools support different extensions, which is both a strength (the format grows to meet new needs) and a challenge (portability between tools can be tricky). Understanding the major flavors helps you write Markdown that works where you need it.
GitHub Flavored Markdown (GFM) is the most widely-used extended flavor. It adds tables, task lists (checkboxes), strikethrough, autolinks, and fenced code blocks with language hints. GFM is based on CommonMark, a standardized, well-specified version of Markdown that resolves many of the ambiguities in the original. Most modern Markdown renderers target CommonMark with GFM extensions.
Other flavors include MultiMarkdown (adds footnotes, citations, and metadata), Pandoc Markdown (a powerful superset used for document conversion), and MDX (Markdown with embedded JSX components, popular in React documentation sites). Each flavor has its own conventions, and content written for one may not render correctly in another. When writing for a specific platform, check its supported flavor and stick to the constructs it handles.
- CommonMark: standardized base specification
- GitHub Flavored Markdown: tables, task lists, strikethrough, autolinks
- MultiMarkdown: footnotes, citations, metadata
- Pandoc Markdown: rich superset for document conversion
- MDX: Markdown with embedded JSX components
The Importance of Live Preview
A live Markdown preview is one of the most useful tools in a developer's writing workflow. It shows the rendered HTML alongside your Markdown source, updating as you type, so you can immediately see how your formatting will appear to readers. This tight feedback loop catches mistakes (a missing space after `#`, an unclosed code fence, a broken link) before they reach your audience.
Without a preview, subtle formatting errors are easy to miss. A list that fails to render because the indentation is off by one space. A code block that swallows the following paragraph because the closing fence is missing. A link that points to the wrong URL because the syntax is slightly off. A preview surfaces these issues instantly, letting you fix them while the context is fresh in your mind.
Beyond catching errors, a preview helps you iterate on style and structure. You can experiment with different heading levels, try reordering sections, and see how tables and images flow within the document. The result is documentation that is not just syntactically correct but genuinely well-structured and readable. A good preview tool also lets you copy the rendered HTML, which is useful when you need to paste formatted content into systems that do not accept Markdown directly.
- Shows rendered HTML alongside your Markdown source
- Catches formatting errors immediately, while context is fresh
- Lets you iterate on structure and style visually
- Often allows copying rendered HTML for systems that do not accept Markdown
Common Markdown Pitfalls
Despite its simplicity, Markdown has several pitfalls that catch even experienced writers. The most common is inconsistent line breaks. In strict Markdown, a single newline within a paragraph is treated as a space, not a line break. To force a line break, you need two trailing spaces or a backslash at the end of the line. Many writers are surprised when their carefully formatted line breaks collapse into a single flowing paragraph.
Another common issue is list indentation. Nested lists require consistent indentation (typically two or four spaces), and mixing tabs and spaces produces broken rendering. Tables require precise pipe placement and a separator row with dashes. Fenced code blocks must have matching opening and closing backticks; an unclosed fence swallows everything after it as code.
Special characters also cause issues. The `*`, `_`, and `#` characters are interpreted as formatting and must be escaped with a backslash when used literally. Angle brackets `<` and `>` may be interpreted as HTML tags. URLs with parentheses (common in Wikipedia links) break link syntax unless properly escaped or wrapped in angle brackets. A live preview catches these issues immediately, but knowing the rules prevents them in the first place.
- Single newlines collapse to spaces — use two trailing spaces for line breaks
- List indentation must be consistent (mixing tabs and spaces breaks rendering)
- Fenced code blocks need matching opening and closing backticks
- Special characters (*, _, #, <, >) must be escaped with backslashes
Best Practices for Writing Markdown
Good Markdown is more than syntactically correct — it is well-structured, readable, and portable. Start with a single H1 at the top of each document (or none, if the title is rendered separately by the publishing system), and use H2 and H3 hierarchically for sections and subsections. Avoid skipping heading levels (jumping from H2 to H4), which breaks navigation in tools that generate tables of contents.
Keep paragraphs reasonably short. Long blocks of text are hard to scan in any format, but especially in Markdown, where the source itself is meant to be readable. Break content into sections with descriptive headings, use lists for step-by-step instructions or enumerations, and use code blocks to set commands and code apart from prose. Add alt text to images for accessibility, and use meaningful link text rather than "click here."
Finally, prefer portable constructs over flavor-specific extensions when possible. Stick to CommonMark + GFM for content that may be read in multiple environments, and save the more exotic extensions for contexts where you know they are supported. Document any non-standard extensions you rely on (a README note like "this document uses GFM task lists") so readers and tools know what to expect. Well-written Markdown ages well and renders cleanly across the many tools and platforms that consume it.
- Use a single H1 and hierarchical H2/H3 structure
- Keep paragraphs short and break content into sections with headings
- Add alt text to images and use meaningful link text
- Prefer portable CommonMark + GFM constructs over flavor-specific extensions
- Document any non-standard extensions you rely on