Markdown is a lightweight markup language that lets you format text using plain-text conventions that look natural when you read them. A heading is # Heading. Bold text is **bold**. A list item starts with a hyphen. Created by John Gruber in 2004, Markdown is now the standard writing format for GitHub README files, technical documentation, blog platforms, note-taking apps, and developer communication tools. Learning it takes less than an hour and eliminates the formatting friction that slows down technical writing.
Core Formatting Syntax
Headings use the hash symbol: # for H1, ## for H2, ### for H3, up to ###### for H6. The number of hashes corresponds to the HTML heading level. Always put a space between the hash and the text. Most renderers also support setext-style headings using underlining with === or ---, but the hash style is more portable and universally supported.
Emphasis uses asterisks or underscores: *italic* or _italic_ produces italics, and **bold** or __bold__ produces bold. Combining them gives ***bold italic***. For inline code, wrap text in backticks: `code`. For strikethrough (supported in GitHub Flavored Markdown), use ~~text~~. These conventions are intuitive because they mirror what people used in plain-text emails before rich formatting existed.
Links use a two-part syntax: [link text](https://url.com). Images are the same with an exclamation mark prefix: . Reference-style links let you define URLs separately: [link text][ref] at the use site and [ref]: https://url.com at the bottom of the document. Reference-style links are cleaner in long documents where URLs would clutter the prose.
Lists, Blockquotes, and Horizontal Rules
Unordered lists use hyphens, asterisks, or plus signs followed by a space: - item, * item, or + item. Ordered lists use numbers followed by a period: 1. item. The actual numbers you use do not matter — Markdown renumbers them automatically — but using 1. 2. 3. in sequence is cleaner to read in the source. Nested lists are created by indenting with two or four spaces.
Blockquotes use the > character: > This is a quote. Multi-line blockquotes can either start every line with > or just the first line, depending on the renderer. Nested blockquotes use >>. Blockquotes render with left-border styling in most Markdown renderers and HTML converters.
Horizontal rules are created by three or more hyphens, asterisks, or underscores on their own line: ---, ***, or ___. These render as HTML hr elements. Paragraphs in Markdown are separated by blank lines — a single line break does not create a new paragraph. This is one of the most common sources of confusion for new Markdown writers.
Code Blocks and Tables
Fenced code blocks use triple backticks before and after the code. Adding a language identifier after the opening backticks enables syntax highlighting: ```javascript. Most Markdown renderers support syntax highlighting for dozens of languages. Indented code blocks (four spaces of indentation) also work but are less readable and do not support language annotation.
Tables are a GitHub Flavored Markdown (GFM) extension. Columns are separated by pipe characters, and the header row is separated from the body by a row of hyphens: | Header | Header | followed by | --- | --- |. Column alignment is controlled by colons in the separator row: :--- for left, ---: for right, :---: for center. Tables are not part of the original Markdown spec but are supported by virtually every modern renderer.
Escaping special characters uses a backslash: \* to display a literal asterisk, \# to display a literal hash. The characters that need escaping are: \, `, *, _, {}, [], (), #, +, -, ., and !. If your formatted text is rendering unexpectedly, check for unintended Markdown triggers in your source.
Converting Markdown to HTML
Markdown is a source format — it needs to be converted to HTML for display in a browser. Every major programming language has a Markdown parser library: marked and markdown-it in JavaScript, python-markdown in Python, kramdown in Ruby. Static site generators like Jekyll, Hugo, and Eleventy convert Markdown to HTML at build time.
When converting Markdown to HTML for user-generated content, always sanitize the output to prevent XSS injection. A user who submits Markdown with an inline HTML <script> tag could execute arbitrary JavaScript if the HTML is rendered without sanitization. Libraries like DOMPurify (browser) and sanitize-html (Node.js) strip dangerous tags while preserving safe formatting.
Extended Markdown flavors add features beyond the original spec. GitHub Flavored Markdown (GFM) adds tables, task lists (- [x] done), and automatic URL linking. CommonMark is a standardized spec that resolves ambiguities in the original Gruber spec. When choosing a parser, confirm it supports the features you need and matches the flavor your content uses.
Markdown reduces the cognitive overhead of writing formatted documents by keeping the source readable without a special editor. Once the syntax becomes muscle memory, you write faster because you never leave the keyboard to click formatting buttons. A Markdown-to-HTML converter is invaluable for testing how your content will render, debugging formatting issues, and generating clean HTML for copy-pasting into content management systems that accept HTML input.