Markdown Preview

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 as-is — even without rendering — while being trivially convertible to HTML and other output formats.

Created by John Gruber and Aaron Swartz in 2004, Markdown was born from a simple philosophy: writing for the web should feel like writing an email. Instead of wrapping text in HTML tags, you use intuitive symbols like # for headings, * for emphasis, and - for lists. The plain text source remains readable and the rendered output is clean HTML.

Today, Markdown is ubiquitous. It powers README files on GitHub and GitLab, documentation on Read the Docs and Docusaurus, note-taking apps like Obsidian and Notion, blogging platforms like Ghost, and static site generators like Astro, Hugo, and Jekyll.

Basic Syntax

Markdown’s core syntax covers the elements you need for most writing tasks:

Headings

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

Each # symbol corresponds to an HTML heading level (<h1> through <h6>). Use one # for the page title and increase levels for subsections.

Emphasis

Syntax	Output	HTML
*italic* or _italic_	italic	<em>
**bold** or __bold__	bold	<strong>
***bold italic***	bold italic	<strong><em>
`inline code`	inline code	<code>

Lists

Unordered lists use -, *, or + as bullet markers. Ordered lists use numbers followed by a period:

- Item one
- Item two
  - Nested item

1. First step
2. Second step
3. Third step

Links and Images

[Link text](https://example.com)
![Alt text](image.png)

Code Blocks

Fenced code blocks use triple backticks with an optional language identifier for syntax highlighting:

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

Blockquotes

> This is a blockquote.
> It can span multiple lines.

Markdown Flavors

The original Markdown specification left many edge cases undefined, leading to divergent implementations. Several “flavors” have emerged to address this:

Flavor	Maintained By	Key Additions
CommonMark	CommonMark team	Formal spec, removes ambiguities
GFM (GitHub Flavored)	GitHub	Tables, task lists, strikethrough, autolinks
MDX	MDX team	JSX components inside Markdown
MultiMarkdown	Fletcher Penney	Footnotes, citations, metadata
Pandoc Markdown	Pandoc team	Footnotes, definition lists, math

CommonMark (2014) is the closest thing to a standard. It provides a formal specification and comprehensive test suite that resolves the ambiguities in Gruber’s original description. Most modern Markdown parsers (markdown-it, remark, pulldown-cmark) implement CommonMark as their baseline.

GitHub Flavored Markdown (GFM) is a superset of CommonMark used by GitHub, GitLab, and many documentation platforms. Its most notable additions are:

• Tables: Pipe-separated columns with alignment support
• Task lists: - [ ] for unchecked and - [x] for checked items
• Strikethrough: ~~deleted text~~
• Autolinked URLs: Raw URLs are automatically converted to clickable links
• Syntax highlighting: Fenced code blocks with language identifiers

Markdown vs Rich Text

Aspect	Markdown	Rich Text (WYSIWYG)
Source format	Plain text	Binary or HTML
Version control	Excellent (text diffs)	Poor (binary diffs)
Portability	Universal	Editor-dependent
Learning curve	Minimal syntax	None (point and click)
Collaboration	Git-friendly	Requires specialized tools
Output formats	HTML, PDF, DOCX, slides	Usually one format
Rendering	Requires parser	Instant in editor

Markdown excels in technical contexts where version control, portability, and collaboration matter. Its plain-text nature means Markdown files produce clean diffs in Git, can be edited with any text editor, and are easily converted to multiple output formats.

Rich text editors (Google Docs, Word, Notion) are better for non-technical users who prefer visual formatting and real-time collaboration without learning syntax.

Common Use Cases

• README files: Every open-source project on GitHub uses README.md as the project landing page
• Technical documentation: Docusaurus, MkDocs, Read the Docs, VitePress, and Astro all use Markdown as their primary content format
• Blog posts: Static site generators (Hugo, Jekyll, Gatsby, Astro) render Markdown files into blog posts with metadata from YAML frontmatter
• Note-taking: Obsidian, Logseq, and Bear use Markdown as their native format, enabling portability and interoperability
• Issue tracking: GitHub Issues, GitLab Issues, and Jira all support Markdown for formatting descriptions and comments
• Chat and messaging: Slack, Discord, and Microsoft Teams support a subset of Markdown for message formatting
• Presentations: Tools like Marp, Slidev, and reveal.js convert Markdown into slide decks