Markdown is a lightweight plain-text format for writing structured content using simple, readable syntax that converts to HTML. It was created by John Gruber in 2004 and is now the de facto standard for content in static site generators, README files, documentation, and many note-taking and collaboration tools.

A Markdown file is just text, it can be edited in any text editor and read by humans without rendering.

Basic syntax

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

Paragraphs are separated by blank lines.

**Bold text** and *italic text*.

- Bullet list item
- Another item

1. Numbered list
2. Item two

[Link text](https://example.com)
![Image alt text](image.jpg)

> Block quote

`inline code` and:

\`\`\`javascript
// code block
function example() {}
\`\`\`

| Table | Header |
| --- | --- |
| Cell | Cell |

The above renders to standard HTML when processed by a Markdown engine.

Common Markdown variants

There is no single official Markdown specification. Several variants extend the original syntax:

CommonMark, a precise specification of core Markdown, used by many modern tools
GitHub Flavored Markdown (GFM), adds tables, task lists, strikethrough, autolinks, used in GitHub repositories and issues
MDX, Markdown extended with JSX (React components) inside content; common in modern documentation sites
MyST, Markdown for scientific and technical documents, used in Jupyter Book and Sphinx
Pandoc Markdown, a feature-rich variant used by the Pandoc document converter

Where Markdown is used

Static site generators. Astro, Hugo, Jekyll, Eleventy, and others read Markdown content files
README files. Standard format on GitHub, GitLab, and other code hosting platforms
Documentation. Tools like Docusaurus, MkDocs, VitePress, and GitBook use Markdown as the source format
Note-taking apps. Obsidian, Bear, Logseq, Roam Research, Notion (in part)
Chat and collaboration. Slack, Discord, Microsoft Teams, Element support Markdown formatting
Headless CMS. Many headless CMS platforms accept Markdown as a content type
Issue trackers. GitHub Issues, GitLab Issues, Linear, Jira (in part)

Markdown vs WYSIWYG

Aspect	Markdown	WYSIWYG
Editor interface	Plain text	Visual, formatted
Learning curve	Low to moderate	Very low
Output	Predictable, standards-based HTML	Variable; can include editor-specific markup
Speed for experienced users	Fast	Moderate
Diff readability (Git)	Excellent	Poor
Portability	High (plain text)	Variable
Collaborative version control	Strong	Limited

Many modern editors blend both: a WYSIWYG-style interface that produces Markdown output, or a live-preview interface where Markdown renders as the user types.

Strengths

Plain text. Future-proof, readable without special software, version-controllable
Predictable output. A given Markdown source produces consistent HTML across renderers (within a variant)
Fast to write. Less mouse use than visual editors for content-heavy work
Easy to diff. Changes show clearly in Git or any text comparison tool
Portable. Markdown files can move between platforms without conversion
Tool ecosystem. Wide support across editors, frameworks, and platforms

Limitations

Limited expressiveness. Standard Markdown does not directly support all HTML capabilities (forms, complex tables, embedded media without extensions)
Variant fragmentation. Differences between Markdown flavors can cause unexpected rendering
Visual content. Tables and complex layouts are clunkier than in a visual editor
Image handling. Inline images require knowing the file path; less convenient than drag-and-drop in WYSIWYG editors

Frontmatter

Many Markdown-based tools use frontmatter, a block of YAML, TOML, or JSON metadata at the top of a Markdown file, to store structured information about the document:

---
title: "My article"
date: 2026-04-23
tags: [web, markdown]
---

The article body starts here.

Frontmatter is processed by the static site generator or CMS but typically not displayed in the rendered output.

MDX

MDX combines Markdown with JSX, allowing React (or other framework) components to be used directly inside Markdown content:

# My article

Here is some text, followed by a custom component:

<InteractiveChart data={chartData} />

More text after the component.

MDX is common in documentation sites and modern frameworks, but it ties content to a specific framework (React, primarily), reducing portability compared to plain Markdown.

Common misconceptions

“Markdown is just for developers.” Many writers and non-technical users adopt Markdown for note-taking and writing because it stays out of the way.
“All Markdown renders the same.” Variants differ; what works in GitHub may not work identically in a static site generator.
“Markdown is limited to simple formatting.” Extensions add tables, footnotes, definition lists, math notation, diagrams, and more.