CommonMark Ready Reference

Preface

Here are a few things you need to know before reading further.

Naming convention

I use the word 'markdown' (in lower case) to refer to any MarkDown implementation, dialect or superset including CommonMark. Specifically, MarkDown means the original MarkDown.

Examples convention

The CommonMark examples are displayed in a

...

block. It has a thick left border. The HTML output of the examples will be in

...

blocks. They will be dashed edges.

Version and dialect

This book is based on Version 0.30 of CommonMark. It may be superseded by newer versions. Whatever the case, the official documentation that came with the version of CommonMark/Markdown that you use in production will always have more relevance.

Although the CommonMark information in this book may apply to MarkDown as well, there are subtle differences between the two. The following text to create a heading passes for MarkDown but not for CommonMark.

#FFMPEG Quick Hacks

You may be expecting this:

Expected output

But, it will not be processed by CommonMark and be output as:

#FFMPEG Quick Hacks

What went wrong? Answer: There has to be a space between the hash and the text. The following is valid CommonMark.

# FFMPEG Quick Hacks

If something from this book does not work with a markdown processor, you need to refer to its documentation.

Then, there are features not supported by both MarkDown and CommonMark, such as strikethroughs and tables. This book sticks to the reference implementation and will not bother with extended syntax supported by markdown extensions. However, this book will suggest workarounds for the same kind of output without using such extensions.

Purpose

Book announcement

The paperback version of this book is for those who need a desk-side reference and for those who would like to learn CommonMark (or MarkDown) at leisure. The paperback is black-n-white or grayscale. Only the cover is in colour. Hence, both covers have been designed as quick reference cards for MarkDown/CommonMark. In the annexures, a grayscale version of the quick reference card is available. You can remove the page and make as many photocopies as you want. (Cut the page with a blade or a pair of scissors. Do not tug at it and ruin the binding.)

If you are on a computer with an Internet connection, there will be plenty of other free alternatives including the official documentation. The ebook version of this book is for people to decide whether it is worth having the paperback on their desk. (The ebook does not include the quick reference card.) The full-colour covers of the paperback is available as a CommonMark/MarkDown cheat sheet or quick reference card on my website. You can print it on a colour printer. Download it for free from:

http://www.vsubhash.in/commonmark.html

Table of Contents

MarkDown and CommonMark

Starting with CommonMark

Build

Usage

Editor

Text

Bold

Italic

Bold-italic

Strikethrough

Paragraphs

Line breaks

Inline code

Escaping

Images

Inline images

Referenced images

Captioned images

Links

Just the URL

Text link

Text link with title attribute

Image link

Reference links

Reference links for citations

Horizontal Rule

A fancy name for a line

Code blocks

Pre-formatted code block

Escape three backquotes or tildes

Code blocks with language hints

Plain pre-formatted text blocks

Headings

ATX headings

Settext headings

Adding heading IDs

Blockquotes

One quoted line - one paragraph

Two adjacent quoted lines - still one paragraph

Two adjacent quoted lines with an empty line in between - two blockquotes

Adjacent lines with quoted empty line in the middle - two paragraphs in one blockquote

Blockquotes with more than just paragraphs

Nested blockquotes

Lists

Ordered lists

Unordered lists

Breaks inside list items

HTML blocks

Unprocessed HTML tags

Processed HTML tags

Exporting to other document formats

MarkDown and CommonMark

In the beginning, there was text. Then, came markup a la HTML. After that, came MarkDown.

Before the invention of the WorldWideWeb (WWW), there was Internet. Communication on this pre-WWW Internet was through email, Usenet, and other text-based protocols. To add context to this text messages, some primitive