Introduction to Markdown

Discover what Markdown is, where it came from, why it has become the universal formatting language for developers and writers, and where you will encounter it.

What is Markdown?

Markdown is a lightweight markup language that uses plain text formatting syntax to create structured documents. It was designed to be readable in its raw form - unlike HTML, which is cluttered with tags, a Markdown document reads naturally as plain text while also being convertible to HTML and other formats.

# Markdown (readable as plain text)
# Welcome to My Project

This is a **bold** statement with a
[link](https://example.com) and a list:

- Item one
- Item two
- Item three

<!-- HTML (cluttered with tags) -->
<h1>Welcome to My Project</h1>
<p>This is a <strong>bold</strong> statement with a
<a href="https://example.com">link</a> and a list:</p>
<ul>
  <li>Item one</li>
  <li>Item two</li>
  <li>Item three</li>
</ul>

History of Markdown

Markdown was created in 2004 by John Gruber (of the blog Daring Fireball) with help from Aaron Swartz. Gruber's goal was simple: create a text-to-HTML conversion tool that was easy to read and write in its source form.

The name "Markdown" is a play on "markup" (as in "markup language") - it is the opposite of marking things up with complex tags. In 2014, a standardized specification called CommonMark was created to resolve ambiguities in the original Markdown spec.

Why Markdown?

Where Markdown is Used

The .md File Extension

Markdown files use the .md extension (or sometimes .markdown). Common files you will encounter:

• README.md - Project description and setup instructions (displayed automatically on GitHub)
• CHANGELOG.md - Log of changes between versions
• CONTRIBUTING.md - Guidelines for contributing to a project
• LICENSE.md - Project license text
• CLAUDE.md - Instructions for Claude Code AI assistant
• AGENTS.md - Instructions for OpenAI Codex agent

Markdown vs HTML vs Rich Text

Markdown Flavors

Over the years, different platforms have extended the original Markdown specification:

• CommonMark: The standardized specification. The baseline for most implementations.
• GitHub Flavored Markdown (GFM): Adds tables, task lists, strikethrough, autolinks, and syntax highlighting.
• MultiMarkdown: Adds footnotes, tables, citations, and metadata.
• Pandoc Markdown: Extensive extensions for academic writing, math, and cross-format conversion.
• Obsidian Markdown: Adds wiki-links, callouts, and knowledge graph features.