Markdown is a lightweight markup language that converts plain text into formatted documents. You write with simple symbols like # for headings, ** for bold, and - for bullet points. A markdown processor then turns these symbols into HTML, PDF, or other output formats.

John Gruber created markdown in 2004 with Aaron Swartz. The goal was a text format that is readable as-is and publishable as HTML without a word processor. Two decades later, markdown is the default writing format for developers, technical writers, and anyone who documents software.

How Markdown Works

You write a plain text file with a .md extension. The file contains your content mixed with formatting symbols:

# Project Setup

Install the dependencies:

```bash
npm install

Then run the development server:

npm run dev

For more details, see the documentation.

A markdown processor reads this file and converts the symbols into HTML:

- `#` becomes `<h1>`
- `**text**` becomes `<strong>text</strong>`
- `[text](url)` becomes `<a href="url">text</a>`
- Fenced code blocks become `<pre><code>` elements

The output is a formatted web page, PDF, or whatever the target format supports.

## Where Markdown Is Used

Markdown is everywhere in the software world and increasingly common outside it:

| Context | How Markdown Is Used |
|---------|---------------------|
| GitHub / GitLab | README files, issues, pull requests, comments, wikis |
| Documentation | Docs-as-code with tools like MkDocs, Docusaurus, VitePress |
| Note-taking apps | Obsidian, Notion (partial), Bear, Logseq |
| Static site generators | Astro, Hugo, Jekyll, Next.js, Gatsby |
| Chat platforms | Slack (partial), Discord, Teams (partial) |
| Developer tools | VS Code, Neovim, Emacs, JetBrains IDEs |
| Email newsletters | Converted to HTML for platforms like ConvertKit, Buttondown |
| Technical writing | API docs, runbooks, RFCs, architecture decision records |

## Why Developers Use Markdown

**It is plain text.** Markdown files work with any text editor. No special software, no proprietary format, no vendor lock-in. A `.md` file from 2004 opens fine in 2026.

**It lives in version control.** Because markdown is plain text, it works naturally with Git. You can diff changes, review in pull requests, and track history. Word documents and Google Docs cannot do this.

**It is fast to write.** Typing `## Heading` is faster than selecting text and clicking a dropdown menu. Once you know the syntax (a few minutes of learning), you rarely need to stop typing.

**It is portable.** The same markdown file can produce a web page, a PDF, a slide deck, or an email. Tools like Pandoc convert between dozens of formats.

**It is readable without rendering.** Unlike HTML or LaTeX, raw markdown is easy to read. A `# Heading` is obviously a heading. A `- list item` is obviously a list item.

## Markdown vs Other Formats

| Feature | Markdown | HTML | Word / DOCX | Google Docs |
|---------|----------|------|-------------|-------------|
| Human-readable source | Yes | No | No | No |
| Version control friendly | Yes | Partial | No | No |
| Open format | Yes | Yes | Partial | No |
| Requires special software | No | No | Yes | Yes (browser) |
| Styling control | Limited | Full | Full | Full |
| Collaboration | Via Git | Via Git | Built-in | Built-in |
| Offline editing | Yes | Yes | Yes | No |
| File size | Tiny | Small | Large | N/A (cloud) |

Markdown trades styling flexibility for simplicity and portability. If you need pixel-perfect layouts, use HTML or a design tool. If you need to write, share, and version content quickly, markdown is the right choice.

## Markdown Flavors

The original markdown specification left many edge cases undefined. Different tools filled the gaps differently, creating "flavors":

**CommonMark** (2014) is a strict specification that resolves the ambiguities in the original spec. Most modern parsers implement CommonMark.

**GitHub Flavored Markdown (GFM)** extends CommonMark with tables, task lists, strikethrough, and auto-linking. It is the most widely used flavor. See [What Is GitHub Flavored Markdown?](/blog/what-is-github-flavored-markdown) for details.

**MultiMarkdown** adds footnotes, citations, cross-references, and metadata.

**Obsidian markdown** extends GFM with callouts, internal links (`[[wikilinks]]`), and embeds.

**MDX** combines markdown with React components. See [What Is MDX?](/blog/what-is-mdx) for more.

For most writing, GFM is the safest choice. It is supported by GitHub, VS Code, most static site generators, and most documentation tools.

## The Basic Syntax

Here is the core markdown syntax at a glance:

| Element | Syntax | Rendered |
|---------|--------|----------|
| Heading | `# H1` through `###### H6` | Heading levels 1-6 |
| Bold | `**text**` | **text** |
| Italic | `*text*` | *text* |
| Link | `[text](url)` | Clickable text |
| Image | `![alt](url)` | Embedded image |
| Code (inline) | `` `code` `` | `code` |
| Code block | Triple backticks with language | Syntax-highlighted block |
| List | `- item` or `1. item` | Bullet or numbered list |
| Blockquote | `> text` | Indented quote |
| Horizontal rule | `---` | Divider line |

For the complete syntax reference, see the [markdown cheat sheet](/blog/markdown-cheat-sheet).

## Getting Started with Markdown

1. **Pick an editor.** Any text editor works: VS Code, Sublime Text, Notepad. For dedicated markdown editing, try Obsidian or Typora. For quick experiments, the [MDtoLink editor](/editor) works in your browser.

2. **Create a file.** Save a new file with a `.md` extension: `notes.md`, `README.md`, `draft.md`.

3. **Write your content.** Use the basic syntax above. Start with headings, paragraphs, and lists. Add links and images as needed.

4. **Preview it.** Most editors have a preview mode (VS Code: `Ctrl+Shift+V`). Or paste your markdown into the [MDtoLink editor](/editor) for instant rendering.

5. **Share it.** Push to GitHub (renders automatically), convert to HTML or PDF, or publish to a URL with [MDtoLink](https://mdtolink.com).

For a step-by-step tutorial, see [How to Write Markdown](/blog/how-to-write-markdown).

## FAQ

### Is markdown a programming language?

No. Markdown is a markup language for formatting text, like HTML. It has no variables, functions, or logic. You write content, not programs.

### What file extension does markdown use?

`.md` is the standard extension. You may also see `.markdown`, `.mdown`, or `.mkd`, but `.md` is used by GitHub, VS Code, and nearly every modern tool.

### Can I convert markdown to HTML?

Yes. Every markdown processor converts to HTML by default. You can use command-line tools like Pandoc, online converters, or the [Markdown to HTML tool](/tools/markdown-to-html) on MDtoLink.

### Do I need special software to write markdown?

No. Any text editor works. Notepad, TextEdit, VS Code, Vim, Nano. Dedicated markdown editors add preview and shortcuts, but they are not required.

### What is the difference between markdown and HTML?

Markdown is a shorthand for HTML. `# Heading` becomes `<h1>Heading</h1>`. Markdown is easier to write and read but supports fewer features. You can embed raw HTML in markdown for anything the syntax does not cover.

## Try It Out

Write your first markdown document in the [MDtoLink editor](/editor) and see the output in real time. When you're ready, publish it to a shareable URL with one click.

For the full syntax, see the [markdown cheat sheet](/blog/markdown-cheat-sheet). To learn about the most popular flavor, see [What Is GitHub Flavored Markdown?](/blog/what-is-github-flavored-markdown).

What Is Markdown? A Plain-English Explanation

How Markdown Works

Publish your markdown to a shareable URL