Markdown Basics

Finally, a developer's markup language for writing

Published on Friday, October 16, 2020

Markdown is a lightweight markup language with plain-text-formatting syntax.

I find using Markdown useful because it is:

  • Easy to focus - Formating never gets in the way. You have the plain text and your thoughts. If necessary, many editors have the option of a real-time preview.
  • Support - Even if not natively supported, there are many extensions for many popular applications like Microsoft Word or WordPress. Write once; use it everywhere.
  • Future proof - Markdown is not going away. It is getting more popular.
  • Easy Syncing or Source Control - Markdown works excellently with version control tools in a plain-text-based format. Easy to track who did what in the document.*
  • Free - Many great markdown tools are free.

Depending on the needs and available extensions, it is possible to do many things beyond simple markup like:

  • Automatic Citations, References, Tables - Pandoc can be used in many cases instead of LaTeX. But LaTeX is still much more capable than any Markdown variant (at the moment). Pandoc comes in many forms; an extended version of Markdown is just one of them
  • UML - PlantUML allows users to create UML diagrams from plain text language. Strictly speaking, it is not a Markdown extension, but it can often be used together.

Some people can find Markdown limited in some cases like:

  • Text Formating - Markdown is not publishing software nor publishing-ready format. But it is good enough for most digital documents.
  • Collaboration - There are no advanced collaboration tools like Microsoft Word or Google Docs support. Markdown is just a markup language. But you can use Markdown with any device that supports real-time collaboration.
  • Comments - There is no 'official' support for comments. Some users (like me) can find it frustrating, depending on the workflow.

Brief Markdown History

In 2004 John Gruber created Markdown language in collaboration with Aaron Swartz. The goal was to allow you "to write using an easy-to-read and easy-to-write plain text format, optionally convert it to structurally valid XHTML (or HTML)"

Readability was the main goal, to enable users basic formatting and text editing, but to be readable as-is, without complex syntaxes, like HTML or RTF (Rich Text Format). Soon after, many extensions and modifications appeared. There were efforts for standardization, but even Gruber was against the idea - "Different sites (and people) have different needs. No one syntax would make all happy."

Basic Markdown Syntax

Markdown syntax is simple and self-explanatory.

# Heading 1
## Heading 2
## Heading 3

This is **bold text**.
This is *italic text*.
This is ***bold and italic***.

> This is a blockquote

1. First item
2. Second item
3. Third item
4. Fourth item

* First item
* Second item
* Third item
* Fourth item


This is [link](
This is <>

Markdown variants

Depending on the use, there are many Markdown extensions/standardizations.

Original Markdown
MultiMarkdown MultiMarkdown
GFM GitHub Flavored Markdown
pandoc Pandoc
Fountain Fountain
CommonMark CommonMark
kramdown-rfc2629 Markdown for RFCs
rfc7328 Pandoc2rfc
Extra Markdown Extra
SSW Markdown for SSW