What is Markdown? A complete guide with examples

Markdown is the lightweight markup language behind almost every README on GitHub, every Notion page, every Discord message with**bold** in it, and the chat output of every modern AI assistant. If you've ever written# Heading or- bullet, you've written Markdown.

This guide answerswhat is Markdown, when to use it, the syntax that matters, and how to turn it into a real document — PDF, Word, or HTML — without the frustration of broken tables and stray asterisks.

Why Markdown beats a rich-text editor

A rich-text editor (Google Docs, Word) saves invisible formatting metadata. Markdown saves visible characters. That sounds like a downside until you've copy-pasted a Word document into Slack and watched the formatting evaporate.

Markdown's promises:

• Plain text — works in any editor, on any platform, in any version-control system.git diff on a Markdown file is meaningful;git diff on a.docx is not.
• Readable as source —**bold** and# heading read fine before they're rendered. Nobody needs to render Markdown to understand it.
• Convertible — the same source becomes HTML, PDF, DOCX, a slide deck, or a static site. Write once, render anywhere.

That's why GitHub, Discord, Slack, Notion, Reddit, Stack Overflow, ChatGPT, Claude, and every static-site generator that matters all speak Markdown.

Markdown syntax — the parts that cover 95% of writing

# Heading 1

## Heading 2

### Heading 3

**Bold** and _italic_ and ~~strikethrough~~.

Inline `code` and code blocks:

```python
print("fenced code block — three backticks")
```

• Unordered list
• Second item
  • Nested

1. Ordered list
2. Second item

Blockquote — for highlighting a quote or callout.

Link text Image alt text

Header	Cell
Body	…

That's the entire CommonMark surface that 95% of writing uses. The remaining 5% — task lists, footnotes, definition lists, math — are flavor extensions covered in the [complete Markdown syntax cheat sheet](/blog/markdown-syntax-cheat-sheet).

## Dialects: CommonMark, GFM, and friends

Markdown isn't one spec. The most important variants:

- **CommonMark** — the formal core. Everyone supports it.
- **GitHub Flavored Markdown (GFM)** — CommonMark + tables, task lists, strikethrough, autolinks. The de-facto standard online. See [GitHub Flavored Markdown: what's different](/blog/github-flavored-markdown).
- **MultiMarkdown / Pandoc** — adds footnotes, citations, math. Academic use.
- **Discord / Slack** — subsets with platform-specific quirks. Covered in [Markdown in Discord](/blog/markdown-in-discord) and [Markdown in Slack](/blog/markdown-in-slack).

If you're writing for a specific platform, write for its dialect. If you're writing portable Markdown, stick to CommonMark + tables and you'll render correctly almost everywhere.

## .md files, .markdown files, and tooling

A Markdown file is just a text file with the `.md` extension (sometimes `.markdown` or `.mdx`). Any text editor opens it. See [MD file: what it is, how to open it, how to convert it](/blog/what-is-an-md-file) for the long version.

Common tooling:

- **Writing**: any text editor. Dedicated apps include Typora, Obsidian, iA Writer, MacDown. See the [Typora alternatives](/blog/typora-alternatives) and [Notion vs Obsidian vs Typora](/blog/notion-vs-obsidian-vs-typora) comparisons.
- **Viewing**: any browser via a [Markdown viewer](/blog/markdown-viewer-online) or natively on GitHub.
- **Converting**: command-line tools like Pandoc, Markdown Tidy for clean web conversions, or libraries like markdown-it (JS) and Python-Markdown.
- **Static sites**: MkDocs, Docusaurus, Astro, Hugo — all consume Markdown. See [MkDocs: getting started](/blog/mkdocs-getting-started).

## Converting Markdown to something useful

The point of Markdown is rarely Markdown itself. It's the rendered output:

- [Markdown to PDF](/blog/markdown-to-pdf) — the most common conversion request
- [Markdown to Word (.docx)](/blog/markdown-to-word) — when stakeholders demand editable Word files
- [Markdown to HTML](/blog/markdown-to-html) — for web publishing or email

The trap: most converters work fine on _clean_ Markdown. They fall apart on real-world Markdown — AI-generated text, copy-pasted from chat, with broken tables and stray characters. That's the gap [Markdown Tidy](/) fills. Paste your Markdown, get a clean PDF or Word file in two clicks.

## What's next

If you write Markdown daily, bookmark the [syntax cheat sheet](/blog/markdown-syntax-cheat-sheet). If you collaborate on docs in Confluence or in a team wiki, see [Confluence and Markdown](/blog/confluence-and-markdown). If you build software, [GitHub Flavored Markdown](/blog/github-flavored-markdown) and the [README.md writing guide](/blog/readme-md-guide) are the next stops.

Or — if you have AI-generated Markdown that just needs to be a polished document right now — paste it into the [editor](/). No signup; runs entirely in your browser.