What is Markdown?
Markdown is a lightweight markup language that turns plain text into formatted documents. Files use the .md extension and can be opened in any text editor.
This page explains what Markdown is, how a Markdown file works, where you will see it, and why it became the default format for docs, notes, and AI chat.
A 30-Second Example
The left side is what you type. The right side is how most apps render it.
# A Markdown file
This paragraph has **bold** and *italic* text.
- First item
- Second item
Visit [MarkdownFormatting](https://markdownformatting.com).
Use `code` for variables.A Markdown file
This paragraph has bold and italic text.
- First item
- Second item
Visit MarkdownFormatting.
Use code for variables.
No tags, no toolbar. The #, *, and backtick characters carry the formatting.
What Is Markdown?
Markdown is a plain-text formatting syntax created by John Gruber and Aaron Swartz in 2004. It lets you add structure and style without writing HTML. Instead of typing <h1>Title</h1>, you type # Title. Instead of <strong>bold</strong>, you type **bold**.
The goal was to make the source readable as-is and easy to convert to HTML. A Markdown document looks good in a text editor, a terminal, and a browser.
There is no single standards body. The original spec is small, but platforms have extended it. GitHub Flavored Markdown, CommonMark, and MultiMarkdown are the main flavors you will run into. Core syntax works almost everywhere; extra features vary by app.
What Is a Markdown File?
A Markdown file is a plain text file that uses the .md extension. It contains Markdown formatting characters. You can create one by renaming a .txt file to .md or choosing Markdown when you save.
Common file names include README.md, CHANGELOG.md, NOTES.md, and ARTICLE.md. Because the file is plain text, it is portable across operating systems, version control, and note apps. The formatting is part of the text itself; no hidden metadata or proprietary format is required.
Most tools that read Markdown convert it to HTML for display. Some also export to PDF, Word, or other formats. The same source can become a GitHub README, a blog post, or a printed document.
Where Is Markdown Used?
Markdown is supported by almost every tool that handles text. These are the places you are most likely to see it.
GitHub, GitLab, and source control
READMEs, pull requests, issues, and comments all use Markdown. GitHub extends it with tables, task lists, alerts, and more.
Documentation sites
Docusaurus, VitePress, MkDocs, and most static-site generators use Markdown as the default format. Writers focus on content; the generator handles HTML.
Note apps
Obsidian, Bear, and many knowledge-base tools store notes as Markdown. The files stay portable, even when the app changes.
Chat and forums
Slack, Discord, Reddit, and Stack Overflow all support Markdown-like formatting. Each platform adds its own quirks and limits.
AI assistants
ChatGPT, Claude, and Gemini read and write Markdown in their replies. It is also the basis for AI files like README.md, AGENTS.md, and llms.txt.
Technical writing and blogging
Technical writers draft in Markdown because it stays out of the way. One source can become a blog post, PDF, slide deck, or book chapter.
Why Markdown Became the Default
Markdown is not the only lightweight markup language, but it is the one most people reach for. A few reasons:
Readable source
A Markdown file is still readable even when it is not rendered. You do not need a special editor to see the structure.
Tiny syntax
The core rules fit on one page. You can be productive in ten minutes.
Tooling everywhere
Every major platform supports Markdown, either natively or through a plugin or converter.
Version-control friendly
Because the file is plain text, Git diffs stay clean and history stays useful.
HTML compatible
When Markdown is not enough, you can drop into raw HTML inline and keep going.
What Markdown Cannot Do
Markdown is intentionally limited. It was designed for writing, not page layout. Standard Markdown has no syntax for:
- Underlined text. Use HTML or platform-specific tricks. See the underline guide.
- Text color or font size. See the text color guide for workarounds.
- Centering, columns, or complex page layout.
- Footnotes, tables, or task lists in the original spec, though many flavors add them.
Different apps also render the same Markdown differently. A table that looks right on GitHub may break in a chat app. When the output matters, test it in the target platform. Our platform guides cover GitHub, Slack, Discord, and Obsidian.
Quick Reference
The most common Markdown syntax in one table.
| Element | Markdown | Result |
|---|---|---|
| Heading | # Title | Top-level heading |
| Bold | **text** | Bold text |
| Italic | *text* | Italic text |
| Link | [text](url) | Clickable link |
| Image |  | Embedded image |
| Unordered list | - item | Bullet list |
| Ordered list | 1. item | Numbered list |
| Inline code | `code` | Monospaced code |
| Code block | ```lang ... ``` | Highlighted block |
| Blockquote | > quote | Quoted text |
| Horizontal rule | --- | Divider line |
Frequently Asked Questions
What is Markdown in simple terms?
Markdown is a way to format plain text using punctuation marks. You type # for headings, * for emphasis, and backticks for code. A renderer converts those characters into formatted HTML.
What is a Markdown file?
A Markdown file is a plain text file with the .md extension. It contains Markdown formatting characters but no proprietary data. You can open it in any text editor, and any Markdown-aware app can render it.
Is Markdown the same as HTML?
No. Markdown is a shortcut for writing HTML. A Markdown document is usually converted to HTML before it is shown in a browser or app. HTML is the output; Markdown is a faster way to produce it.
Is Markdown a programming language?
No. Markdown is a markup language. It describes structure and formatting, but it does not run logic, make decisions, or execute commands.
Do all apps use the same Markdown?
No. There are several flavors. CommonMark is the closest thing to a modern standard. GitHub Flavored Markdown adds tables, task lists, and alerts. Slack uses mrkdwn, Discord has its own rules, and Obsidian adds wikilinks and callouts. Core syntax is mostly the same; extras differ.
Should I learn Markdown?
Yes, if you write documentation, take notes, use GitHub, chat with AI assistants, or communicate in technical communities. The basics take under an hour and repay the time immediately.
Can I use Markdown for a website?
Yes. Static site generators like Hugo, Eleventy, Astro, Jekyll, and Next.js can turn Markdown files into full HTML sites. You can also convert Markdown to HTML with tools like Pandoc, marked, or your editor's export feature.
Related Guides
Start writing, or explore a topic that interests you.