Markdown Guide: Complete Syntax Reference 2026
Markdown was created in 2004 by John Gruber as a way to write text that looks good as plain text and converts cleanly to HTML. Two decades later it is the default writing format for developers, technical writers, and content creators worldwide. Despite its simplicity, Markdown has dozens of syntax elements that new and intermediate users miss. This complete reference covers every major Markdown feature — from basic headings to advanced GFM extensions — with copy-ready examples for each. Keep it bookmarked and use the WikiPlus Markdown Preview tool to test any snippet as you go.
Basic Markdown Syntax: Headings, Paragraphs, and Emphasis
The building blocks of any Markdown document are headings, paragraphs, and text emphasis. Headings are created with hash characters. A single # gives you an H1, ## gives H2, up to ###### for H6. Always put a space between the hash and the text. Some parsers are strict about this and will not render the heading without the space. Paragraphs are simply one or more lines of text separated by a blank line. A single line break within a paragraph does not create a new paragraph — you need the blank line. If you want a line break without starting a new paragraph, end the line with two or more spaces (or a backslash in some parsers). Text emphasis works with asterisks or underscores. Single markers give italic: *italic* or _italic_. Double markers give bold: **bold** or __bold__. Triple markers give bold italic: ***bold italic***. Underscores work inside words inconsistently across parsers, so asterisks are the safer choice. Horizontal rules are three or more hyphens, asterisks, or underscores on a line by themselves: ---. These render as an HTML `<hr>` element and are useful for separating major sections. Blockquotes use a > character at the start of each line. You can nest blockquotes with >> for a second level. Blockquotes support other Markdown syntax inside them, including bold, lists, and code. Inline code uses single backticks: `code here`. For code that contains a backtick itself, wrap it in double backticks: `` `code` ``.
Links, Images, and Lists in Markdown
Links follow the pattern [link text](URL). For links with titles that appear on hover, add a quoted string after the URL: [link text](URL "Title text"). Reference-style links separate the URL from the text: [link text][label] in the body, then [label]: URL at the bottom of the file. This is useful when the same URL appears multiple times or when URLs are very long. Automatic links work by wrapping a URL or email in angle brackets: <https://example.com> or <email@example.com>. Most modern parsers also auto-link bare URLs without the angle brackets. Images use the same syntax as links but with an exclamation mark prefix: . The alt text is critical for accessibility and SEO. For images with titles: . Images also support reference style: ![alt text][img-ref] with [img-ref]: image-url at the bottom. Unordered lists use -, *, or + at the start of each item followed by a space. Nested lists are created by indenting the child items by two or four spaces. Ordered lists use numbers followed by a period: 1., 2., 3. Interestingly, the actual numbers do not matter in most parsers — they just count from the first number you use. So 1., 1., 1. renders as 1, 2, 3. Definition lists are supported in some extended Markdown flavors but not CommonMark. For maximum compatibility, use a bold term followed by a colon and the definition as a regular paragraph.
Code Blocks, Tables, and GFM Extensions
Fenced code blocks start and end with three backticks (```) on their own lines. Add a language identifier after the opening backticks for syntax highlighting: ```javascript, ```python, ```bash. Indented code blocks (four spaces) still work but are considered legacy — fenced blocks are preferred for clarity and feature support. GFM tables use pipe characters to separate columns and a separator row to define alignment. The minimum table looks like this: | Column 1 | Column 2 | | --- | --- | | Cell 1 | Cell 2 | Alignment is set with colons in the separator row. Left-align: :---. Right-align: ---:. Center: :---:. Every row must have the same number of pipes. Extra spaces around pipes are ignored and can help readability. Task lists are GFM checkboxes created with - [ ] for unchecked and - [x] for checked. They render as interactive checkboxes on GitHub and in some editors. Strikethrough uses double tildes: ~~struck through~~. This is a GFM extension not in CommonMark. Footnotes are supported in many extended Markdown flavors. The syntax is [^1] inline and [^1]: Footnote text at the bottom. CommonMark does not include footnotes in its spec, but many parsers support them as an extension. HTML is valid inside Markdown documents in most parsers. Block-level HTML elements like <div>, <table>, and <pre> must be separated from surrounding Markdown by blank lines.
Escaping, Special Characters, and Common Mistakes
Backslash escapes let you display characters that Markdown normally treats as formatting syntax. If you need to show a literal asterisk, write \*. This works for: \` \* \_ \{ \} \[ \] \( \) \# \+ \- \. \! HTML entities work inside Markdown: & for &, < for <, > for >, © for ©. Numeric character references also work: © for ©. Common mistakes that break rendering: Missing blank lines — the most frequent problem. A heading, list, code block, or table that runs directly against the paragraph above it often fails to render. When something looks wrong, add a blank line before and after it. Mixed spaces and tabs for list indentation — pick one and be consistent. Tabs can cause unexpected nesting behavior. Forgetting the separator row in tables — a GFM table without the | --- | row will render as plain text in most parsers. Nesting inline code inside emphasis — `**bold and \`code\`**` does not work as expected in all parsers. Keep inline code on its own without nesting it inside bold or italic markers. Using > without a space — some parsers require > followed by a space to create a blockquote. `>text` may not render; `> text` always does. The WikiPlus Markdown Preview tool is the fastest way to check any of these. Paste the suspect Markdown into the editor and see immediately whether it renders correctly. The download button lets you export the validated HTML for use elsewhere.
Frequently Asked Questions
- What is the difference between Markdown and MDX?
- MDX (Markdown with JSX) is an extension of Markdown that allows you to use JSX components — essentially React components — directly inside Markdown files. Standard Markdown converts to static HTML. MDX converts to a React component tree, making it possible to embed interactive UI elements, data visualizations, and custom components inline. MDX is used by documentation frameworks like Docusaurus, Nextra, and Astro. Standard Markdown previewers like WikiPlus do not render JSX components, but they handle the Markdown text portions of MDX files correctly.
- Is Markdown the same as reStructuredText?
- No. reStructuredText (rST) is a different plaintext markup language used primarily in Python documentation via the Sphinx documentation generator. It has different syntax for nearly everything — headings use underline characters, links use backticks with underscores, and directives use a .. prefix. Markdown is more widely adopted outside the Python ecosystem. The two are not interchangeable, and a Markdown previewer will not correctly render rST files.
- Can I use Markdown in Google Docs or Microsoft Word?
- Google Docs has a built-in Markdown import feature (File > Open) that converts a .md file to formatted Docs content. It also has an experimental Markdown mode in Tools > Preferences. Microsoft Word does not natively support Markdown, but you can use Pandoc (a free command-line tool) to convert .md files to .docx. Alternatively, paste rendered HTML from the WikiPlus Markdown Preview download into Word, which preserves most formatting.