Last Updated on December 24, 2022
Markdown is a plain text formatting syntax created by John Gruber in 2004. It’s designed to be easy-to-read and easy-to-write.
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 *.
Markdown has a much more basic syntax than HTML, leaving aside things like opening and closing tags, and instead uses punctuation and characters that all users will already use in daily writing. The punctuation characters have been carefully chosen to resemble what they mean. The intention is to ensure that the syntax does not stop the flow of writing, allowing the author to focus on content, rather than how it looks. In this way, Markdown shares a common bond with LaTeX, a document preparation system for high quality typesetting, which also encourages authors not to focus too much on the appearance, but to concentrate on the right content.
Markdown can be easily read with any text editor. There are powerful online Markdown editors. Further, there are syntax highlighting plugins available for standard text editors such as Emacs, vim, and gedit.
Advanced writers are often drawn to Markdown primarily because it helps with writing flow. The problem with many traditional wordprocessors is that it’s too easy to worry about the visuals of the text and use a mouse to fix the formatting and style. This process can often lead to a disjointed experience where concentration is continually broken. Markdown allows you to keep your fingers firmly planted on the keyboard with formatting applied on the fly.
Markdown is free software, available under the terms of a BSD-style open source license.
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 favourites.
R Markdown Cheat Sheet
Mastering Markdown
Good and Bad about Markdown
| Good | Bad | ||
|---|---|---|---|
 | Formatting text has a very gentle learning curve |  | No standard implementation. Multiple implementations with different variations |
| Fast - much quicker than using HTML tags, and often quicker than using a word processor | | Popular tools that use Markdown implement their own flavour |
| Clean - translates quickly to well-formed HTML | | No extensibility - users cannot extend the language to add new functionality |
| Flexible - output your documents to a wide array of formats. | | Lack of semantic meaning |
| Fits any workflow | | Difficult to migrate Markdown code to different tools. |
Useful Software
Write Markdown with 8 Exceptional Open Source Editors – recommended Markdown Text Editors.
Markdown Here– a useful Google Chrome, Firefox, Safari, Opera, and Thunderbird extension that lets you write email in Markdown and render them before sending. It also supports syntax highlighting (just specify the language in a fenced code block).
pandoc – converts files from one markup format into another.
Dillinger – a cloud-enabled, mobile-ready, offline-storage, AngularJS powered HTML5 Markdown editor.
StackEdit – a full-featured, open-source Markdown editor based on PageDown.
There is some standardization at the core functionality but then there are extra custom syntax options on some clients/sites.
All of the fundamentals like bold, italics, links, images, headers, quotes, etc are all done the same way on every implementation of Markdown. It only gets modified when you go into special custom platform features.
Markdown really isn’t meant to be a coding language anyway so when Markdown doesn’t have some function, you are suppose to compensate with HTML.