Markdown Guide

What is Markdown?

Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents. It allows you to create formatted text using a simple, easy-to-read syntax that can be converted to HTML and other formats.

Think of Markdown as a way to write formatted documents without needing complex word processors. You simply add special characters to plain text to indicate formatting like bold, italic, or code.

Why Use Markdown?

Markdown is incredibly simple and easy to learn. You can master the basics in just 10 minutes. The formatting symbols are intuitive - asterisks for emphasis, hashes for headings. You just type and add simple symbols to format your text.

Markdown works on any platform and any text editor. Since files are plain text, they will always be readable, even decades from now. The files are lightweight and load quickly.

Markdown has wide support across platforms. GitHub, Reddit, Discord, and Slack all use Markdown. Popular apps like Obsidian, Notion, and VS Code support it natively. This makes it perfect for documentation, note-taking, and web content.

Markdown works perfectly with version control systems like Git. You can focus on content without formatting distractions. Team collaboration is easier because everyone can edit files without special software.

Markdown Development History

The Beginning: Vanilla Markdown (2004)

Markdown was originally created by John Gruber in 2004, with significant input from Aaron Swartz. Gruber designed it to be a simple way to write using an easy-to-read and easy-to-write plain text format that could be converted to structurally valid HTML. This is the "core" that John Gruber initially designed and implemented, containing the most basic formatting syntax - what we call the "basic vanilla flavor".

Basic Syntax (Vanilla Markdown includes):

  • •
    Headers: Use # symbol (# Header)

  • •
    Emphasis:

  • •
    Italic: Use * or _ to wrap text (*italic* or _italic_)
  • •
    Bold: Use ** or __ to wrap text (**bold** or __bold__)

  • •
    Lists:

  • •
    Unordered lists: Use *, -, or + (- item)
  • •
    Ordered lists: Use numbers with periods (1. item)
  • •
    Links: Use [link text](link address)
  • •
    Images: Use ![image description](image address)

  • •
    Code blocks: Indent with spaces (usually 4 spaces or 1 Tab)

  • •
    Blockquotes: Use > symbol (> This is a quote)
  • •
    Horizontal rules: Use --- or ***

The Problem: Inconsistent Implementations

However, Vanilla Markdown lacked a strict, formal specification. This led to inconsistent behavior across different Markdown parsers when handling edge cases.

Whitespace handling: For example, in list items, how many spaces of indentation count as a sub-list? Is it 2 spaces, 3 spaces, or 4 spaces? Different parsers might have different judgments.

Line break processing: In certain situations, should a regular line break(\n) be parsed as a <br> (line break) tag, or should it simply be treated as a space in the text? This can also vary depending on the parser.

HTML mixed usage: Markdown allows embedded HTML. However, in some complex HTML structures, how Markdown parsers handle Markdown syntax within them also presents ambiguous areas.

The Solution: CommonMark (2014)

In September 2014, CommonMark was introduced to solve these inconsistency problems. Led by John MacFarlane, it provides a rigorous specification for Markdown.

CommonMark provides a precise specification where every edge case is clearly defined. It includes a comprehensive test suite with over 600 test cases to ensure consistency across implementations. The specification provides a reference implementation that serves as a standard for other parsers to follow. It maintains backwards compatibility with most existing Markdown documents while ensuring unambiguous parsing where the same input always produces the same output across all compliant parsers.

Extended Flavors and Additional Features

As users had different needs, various extended flavors of Markdown emerged to meet specific requirements.

GitHub Flavored Markdown (GFM) Additional Syntax:

  • •
    Tables: Use pipe syntax to create tables
  | Header 1 | Header 2 | Header 3 |
  |----------|----------|----------|
  | Cell 1   | Cell 2   | Cell 3   |
  | Cell 4   | Cell 5   | Cell 6   |
  • •
    Strikethrough: Use ~~ to wrap text (~~deleted text~~)

  • •
    Task Lists: Create interactive checkboxes

  - [x] Completed task
  - [ ] Incomplete task
  • •
    Fenced Code Blocks: Use triple backticks with language specification
  ```javascript
  function hello() {
    console.log("Hello World!");
  }
  ```
  • •
    Automatic Linking: URLs and email addresses become clickable automatically

Other Popular Extensions:

  • •
    Footnotes: Use [^1] syntax for academic writing
  This is a sentence with a footnote[^1].
  [^1]: This is the footnote content.

Result: This is a sentence with a footnote¹.

  • •
    Math Expressions: Use $E=mc^2$ for scientific documents
  • •
    Emoji Shortcuts: Use :smile: becomes 😊

  • •
    Definition Lists: For glossaries and technical documentation

  Term 1
  : Definition for term 1
  
  Term 2
  : Definition for term 2
  : Another definition for term 2

Result: Creates formatted lists with highlighted terms and indented definitions

How Does it Work?

Markdown follows a simple three-step workflow:

Step 1: Create a Markdown File

First, you create a plain text file with a .md or .markdown extension using any text editor. You write your content using simple formatting symbols:

Step 2: Process with Markdown Tools

Your .md file is then processed by Markdown conversion tools or processors. These tools read your Markdown file and convert it to the desired output format.

Step 3: Output to Various Formats

The Markdown processor can convert your file to multiple formats:

For Web Display:

  • •
    Converts to HTML for websites, blogs, and web applications

  • •
    Displays formatted content in browsers with proper styling

For Documents:

  • •
    Converts to PDF for printable documents and reports

  • •
    Generates Word documents (.docx) for office use
  • •
    Creates LaTeX for academic papers and publications

For Publishing:

  • •
    Generates eBooks (EPUB format)

  • •
    Creates presentation slides
  • •
    Produces documentation websites

This workflow means you write once in Markdown, then use different tools to convert your content to whatever format you need - whether it's displaying on a website, printing as a PDF, or sharing as a document.

Additional Resources

Essential Documentation

  • •
    John Gruber's Markdown documentation :The original guide written by the creator of Markdown. Essential reading for understanding the philosophy and basic syntax.

  • •
    Wikipedia - Markdown :Comprehensive overview of Markdown's history, variations, and technical details.

  • •
    Markdown Guide :A comprehensive, beginner-friendly guide with examples and best practices for all skill levels.