Last Updated on October 25, 2024
Markdown is a plain text format for writing structured documents. It’s a simple way to format text that looks great on any device. It doesn’t do anything fancy like change the font size, color, or type — just the essentials, using keyboard symbols you already know.
Readability is at the very heart of Markdown. It offers the advantages of plain text, provides a convenient format for writing for the web, but it’s not intended to be a replacement for HTML. Markdown is a writing format, not a publishing format. You control the display of the document; formatting words as bold or italic, adding images, and creating lists are just a few of the things we can do with Markdown. Mostly, Markdown is just regular text with a few non-alphabetic characters included, such as # or *.
Unfortunately, Markdown has embarked in a hundred-and-one different directions, each with its own syntax. CommonMark seeks to provide a complete, unambiguous specification of the language to promote adoption of the language and ensure that documents display the same on all platforms.
CommonMark is a strongly defined, highly compatible specification of Markdown, along with a suite of comprehensive tests to validate implementations against the specification.
It was originally called Standard Markdown but renamed to CommonMark following objections from John Gruber, the original creator of Markdown. CommonMark is released under the Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) License.
CommonMark has BSD-licensed reference implementations in C and JavaScript. The spec is a Markdown file with over 500 embedded code examples written in shorthand form which serve as conformance tests.
Ways to Learn
bookdown: Authoring Books and Technical Documents with R Markdown
By Yihui Xie (HTML; 240 pages)
This short book introduces an R package, bookdown, to change your workflow of writing books. It should be technically easy to write a book, visually pleasant to view the book, fun to interact with the book, convenient to navigate through the book, straightforward for readers to contribute or leave feedback to the book author(s), and more importantly, authors should not always be distracted by typesetting details.
The online version of this book is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. A hardcopy is available to purchase.
Guides
Most good Markdown editors come with a built-in cheat sheet to make it a little easier to learn. But here’s our standalone favorites. They are not specific to CommonMark with the exception of the Quick Reference card.
Quick Reference card
R Markdown Cheat Sheet
Mastering Markdown
Good and Bad about CommonMark
| Advantages | |
|---|---|
 | Markdown has been characterised by an informal specification. CommonMark seeks to correct the position |
| Editors that support CommonMark include Caret, ghostwriter, Markdown Writer FX, and Visual Studio Code |
| Seeks to remain faithful to John Gruber’s original Markdown syntax description |
| GitLab uses "GitLab Flavored Markdown" (GFM). It extends the CommonMark specification (which is based on standard Markdown) |
| Adoption by Discourse and GitHub (GitHub Flavored Markdown is based on CommonMark) |
| Disadvantages | |
|---|---|
 | Finalized 1.0 spec and test suite not released. Latest version release (0.28) released August 2017 |
| Many other implementations of Markdown are available |
| Limited number of editors that support CommonMark |
Useful Software and Websites
Write Markdown with 8 Exceptional Open Source Editors – recommended Markdown Text Editors.
league/commonmark – a Markdown parser for PHP which supports the full CommonMark spec.
markdown-it – Markdown parser, done right. 100% CommonMark support, extensions, syntax plugins & high speed.
commonmark.js – CommonMark parser and renderer in JavaScript.
CommonMark – Python parser for the CommonMark Markdown spec.
lcmark – a flexible CommonMark renderer in Lua, with templates, YAML metadata, and filters.
cmark – CommonMark parsing and rendering library and program in C.