Markdown Guide

What it is

The Markdown Guide is a free and open-source reference to Markdown created by Matt Cone. It is organised into Getting Started, a one-page Cheat Sheet, Basic Syntax, Extended Syntax, Hacks and a Tools directory. Every element is shown as the Markdown you type next to the HTML it produces and the rendered result, and the site's source is on GitHub under a Creative Commons licence.

Is it worth your time?

Yes, especially if you write READMEs, docs, pull request descriptions or blog posts. Markdown looks simple, but small details decide whether a document renders correctly: blank lines around lists, indentation inside numbered steps, escaping characters, and which extensions a given app supports. The guide covers these details with a best practices note under many elements, which is where most of its value lies.

What it covers

• Basic syntax: headings, paragraphs, line breaks, emphasis, blockquotes, lists, code, horizontal rules, links, images and escaping.
• Extended syntax: tables, fenced code blocks, footnotes, heading IDs, definition lists, strikethrough, task lists, emoji, highlight, subscript, superscript and automatic URL linking.
• Hacks: workarounds for things Markdown lacks, such as underlining, centring, colour, comments and image sizing, and when they work.
• Tools: a directory of apps and sites showing which syntax elements each one supports.

How long it takes

About an hour to read the basic and extended syntax pages. After that, most people keep the cheat sheet open or come back to a single page when something renders strangely.

Prerequisites

None. It is written for complete beginners and is still useful to experienced writers.

Free or paid?

The website is free. The same author sells The Markdown Guide book, around 60 pages in PDF and EPUB, for $5 on the book page, with a free sample; you do not need it to use the site.

What you can do after it

Write READMEs and documentation that render the same everywhere, format tables and nested lists without trial and error, and know when a feature is an extension that may not work on a given platform.

Common questions

Does it cover GitHub-specific features? It covers the extensions GitHub shares with other tools, such as tables, task lists and footnotes. For GitHub-only features such as alerts, mentions and Mermaid diagrams, use GitHub's own formatting docs.

Is Markdown the same everywhere? No. The guide explains the difference between basic and extended syntax and uses its Tools pages to show what each app supports.