Markdown guides & tutorials
Everything we know about writing in Markdown — from the basics to exporting a finished document. Written for people who write, not just for developers.
Guide
Markdown Guide
A complete, practical Markdown guide with every syntax element and a printable cheat sheet — headings, lists, links, images, tables, code and task lists.
Best Markdown Editor for Mac
The best Markdown editors for macOS compared — Inkiostro, Typora, Obsidian, iA Writer, Bear and Ulysses. Prices, live preview, LaTeX, Mermaid, EPUB, and which .md reader to use.
Best Markdown Editor for iPad
The best Markdown editors for iPad and iPhone compared — Inkiostro, iA Writer, Obsidian, Bear and Ulysses — plus the well-known Mac editors that have no iPad app at all.
Basics
Syntax
Headings
The six heading levels in Markdown, how many # to use, why one H1 per document matters, and the anchor links headings generate. With a live editor.
Bold & Italic
How to write bold, italic, bold italic and strikethrough in Markdown, when asterisks beat underscores, and why emphasis inside a word can fail.
Line Breaks & Paragraphs
Why pressing Enter once does nothing in Markdown, and the three ways to force a line break — two spaces, a backslash, or a blank line. Try each one live.
Lists
Bulleted, numbered and nested lists in Markdown, why your indentation breaks them, and the difference between tight and loose lists. With a live editor.
Links
Inline links, reference links, anchors to headings, titles on hover and automatic URLs — every way to write a link in Markdown, with a live editor.
Images
How to add an image in Markdown, why the alt text matters, how to make one a link, and what to do about image size. With a live editor to try it in.
Code Blocks
Inline code with backticks, fenced code blocks with syntax highlighting, and how to show backticks themselves. With a live editor to try each form in.
Tables
Build a Markdown table with pipes and dashes, set column alignment with colons, and handle the things tables cannot do. With a live editor to try it in.
Task Lists
How to write checkboxes in Markdown with - [ ] and - [x], where they render as clickable boxes, and how to nest them. With a live editor to try it in.
Blockquotes
How to quote text in Markdown with the greater-than sign, nest quotes, put lists and code inside them, and write callouts. With a live editor.
Horizontal Rules
Three ways to draw a divider in Markdown, the blank-line trap that turns your rule into a heading, and how front matter uses the same characters.
Escaping
How to show a literal asterisk, underscore, hash or backtick in Markdown, the full list of escapable characters, and when a backslash is unnecessary.
Footnotes
How to write footnotes in Markdown with the caret syntax, where they are supported, and what to do when they are not. With a live editor to try it in.
Background
How-to
Markdown to PDF
How to convert Markdown to a polished PDF — with headers, footers, page numbers and margins. A simple step-by-step method on Mac, iPad and iPhone.
Math in Markdown
Write beautiful math in Markdown using LaTeX syntax — inline and block equations rendered with KaTeX. Syntax, examples and how to export equations to PDF.
Diagrams in Markdown
Create flowcharts, sequence and other diagrams in Markdown using Mermaid — draw with plain text instead of a mouse. Syntax, examples and how to export them.