MarkdownPaper Open reader

Guide

What is Markdown?

Markdown is a way to format text using ordinary characters. You type a # before a line to make it a heading, wrap a word in ** to make it bold, and start lines with - to make a list. The file stays plain text, so anyone can read it as it is, and a Markdown reader turns it into a formatted page.

You write

# Shopping list

Get these **before Friday**:

- Coffee
- Bread
- Paper for the printer

You see

Shopping list

Get these before Friday:

  • Coffee
  • Bread
  • Paper for the printer

On the left is what you type. On the right is what a reader shows. That is the whole idea.

5 min read8 sectionsUpdated 1 Oct 2026

On this page

Why people use it

Markdown was made in 2004 by John Gruber, with Aaron Swartz, so that writing for the web would not mean writing HTML. The goal was text that reads well even before it is formatted. A Markdown file still makes sense in a plain text editor, in an email, or printed out.

That turned out to be useful well beyond the web:

  • It is just text. Any computer can open it, it works with Git, and it will still open in thirty years.
  • It is quick to write. No toolbar, no menus. Your hands stay on the keyboard.
  • It looks the same everywhere it is rendered. A heading is a heading on GitHub, in your notes app and in a reader.

Where you will see it

  • README files. The front page of almost every project on GitHub is a file called README.md. See what a README file is.
  • Documentation. Many software docs sites are written in Markdown and turned into web pages.
  • Notes apps. Obsidian, Bear, Notion and others use Markdown or something close to it.
  • AI tools. ChatGPT, Claude and Gemini answer in Markdown, which is why their replies come back with headings, lists and code blocks. Coding agents write their plans as .md files too.
  • Chat and forums. Slack, Discord, Reddit and GitHub comments all accept some Markdown.

What a .md file is

A file that ends in .md (sometimes .markdown) is a plain text file written in Markdown. You can open it in any text editor and see the symbols, or open it in a Markdown reader and see the formatted page. If you have one and want to read it, see how to open a .md file.

What Markdown can do

Here is most of everyday Markdown in one block:

You write

## A heading

A paragraph with **bold**, *italic* and `code`.

1. A numbered list
2. With two items

> A quote from someone else.

| Name | Role   |
| ---- | ------ |
| Ana  | Design |
| Ben  | Code   |

[A link](https://example.com)

```js
console.log('Code, with colors');
```

You see

A heading

A paragraph with bold, italic and code.

  1. A numbered list
  2. With two items

A quote from someone else.

NameRole
AnaDesign
BenCode

A link

console.log('Code, with colors');

Every one of these has its own guide. Start with the Markdown tutorial if you want to learn by writing, or keep the Markdown cheat sheet open as a reference.

Markdown, HTML and Word

HTML is what web pages are made of. It can do far more than Markdown, but it is slow to write and hard to read as text. Markdown covers the common parts of a page, and most Markdown renderers also let you drop in a little HTML when Markdown cannot do something.

Word and Google Docs store formatting inside the file in a way only those apps understand. Markdown keeps the formatting in the text itself, so it works in any editor and travels well. The trade off is that Markdown has no page layout, fonts or colors of its own. Those come from whatever shows it.

Different flavours

The original Markdown left some things unclear, so a few versions grew up. CommonMark is a precise standard for the basics. GitHub Flavored Markdown adds tables, task lists, strikethrough and footnotes on top of it, and it is what most tools mean today when they say Markdown. Some apps add their own extras, like maths or diagrams. The basics work the same everywhere.

Questions

Is Markdown a programming language?

No. Markdown is a formatting language. It describes how text should look, not what a computer should do. You do not need to know how to code to use it.

What app do I need to write Markdown?

Any text editor works, even Notepad or TextEdit. Editors made for Markdown, like VS Code, Typora or Obsidian, add a preview and shortcuts. To read a finished file, use a Markdown reader.

Is Markdown the same everywhere?

The basics are: headings, bold, italic, lists, links, images and code. Tables, task lists and footnotes come from GitHub Flavored Markdown, which most tools support. Maths, diagrams and callouts depend on the app.

Why do AI tools reply in Markdown?

Because it is plain text that still carries structure. A model can write headings, lists and code blocks with a few characters, and the chat app turns them into a formatted answer. If you copy an answer out, you often get the Markdown, which is why it is worth knowing how to read it.

Next