Markdown Guide: What is Markdown? A Beginner's Tutorial

What is Markdown?

Markdown is a lightweight markup language that lets you format plain text using simple symbols. It was created by John Gruber in 2004, with technical input from Aaron Swartz, with the goal of making text that is easy to read in its raw form and easy to convert into HTML for the web.

Instead of clicking buttons in a toolbar to make text bold or create a heading, you type simple characters like ** for bold and # for headings. The result is a plain text file that any computer can open, but that can also be rendered as a beautifully formatted document.

Markdown files usually end in the .md or .markdown extension. Because they are plain text, they open in any editor (Notepad, TextEdit, VS Code, vim) without special software. Yet when viewed on GitHub, Reddit, Obsidian, or most note apps, the same file renders with headings, bold, italics, lists, and links applied.

The problem markdown solves is a split that existed between plain text (portable, easy to read, no formatting) and rich text formats like Word or Google Docs (nice formatting, but locked into proprietary binary files). Markdown gives you both: readable source text plus rendered output, all from the same file.

Today, markdown is used by millions of people for everything from developer documentation to personal notes. If you have ever written a README file on GitHub or formatted a message on Reddit, you have already used markdown.

Why Use Markdown?

Markdown has four qualities that keep it popular decades after it was first released:

How Does Markdown Work?

The markdown workflow has three steps:

1. Write your content in plain text using markdown syntax (# for headings, ** for bold, etc.).
2. Process the file through a markdown parser. The parser reads your symbols and converts them into structured output.
3. Output the result as HTML, PDF, or another format ready for display or publishing.

For example, when you write **hello** in markdown, the parser converts it to <strong>hello</strong> in HTML, which your browser renders as hello.

Markdown vs HTML

Markdown and HTML both describe how text should be formatted, but they target different jobs. Markdown is for writing; HTML is for web page structure. The table below shows the practical differences.

In practice, most websites use a mix: authors write content in markdown, and a parser converts it to HTML at build time or page load. You get the speed and readability of markdown for writing, and HTML for rendering in the browser.

Markdown Tutorial: Your First Document

This short markdown tutorial shows the most common formatting elements in one file. Copy the example and paste it into our markdown editor to see the formatted result instantly.

# My First Document

This is a paragraph of text. Markdown lets you write
**bold text**, *italic text*, and [links](https://example.com).

## Shopping List

- Apples
- Bread
- Coffee

## Notes

> Markdown is simple to learn and powerful to use.

That is all you need to get started!

That is everything you need to write a formatted document. The # symbol creates headings, ** makes text bold, * makes it italic, dashes create bullet lists, and > creates blockquotes.

Common Markdown Syntax

These are the ten markdown elements you will use most often. For a deeper reference, see our full syntax guide or the cheat sheet.

# Heading 1

## Heading 2

**bold text**

*italic text*

[text](https://url.com)

![alt](image.jpg)

- Item one
- Item two

1. First
2. Second

`code`

> Quoted text

Where to Use Markdown

Markdown shows up in more places than you might expect. Here are the most common use cases:

• -Documentation - README files, API docs, wikis, and knowledge bases.
• -Notes - Personal and team notes in apps like Obsidian, Notion, and Bear.
• -Websites - Static site generators like Next.js, Hugo, Jekyll, and Gatsby use markdown for content.
• -Messages - Slack, Discord, Reddit, and GitHub comments all support markdown formatting.
• -Email - Some email clients and tools let you compose messages in markdown.
• -AI prompts - Markdown is the default input format for ChatGPT, Claude, and most large language model interfaces.

Markdown Flavors

Over the years, different organizations have created their own extensions to the original markdown specification. Here are the most important ones:

Who Created Markdown?

John Gruber, author of the blog Daring Fireball, released the first version of markdown on March 19, 2004. He designed it with a single goal: writing for the web should be readable as plain text. Aaron Swartz, the programmer and activist, helped shape the syntax in email exchanges with Gruber during the design phase.

The original spec was informal and had ambiguous edge cases, which led different tools to render markdown differently. GitHub popularized the format in 2009 when it began rendering README files as markdown. In 2014, a group of developers published CommonMark, a strict specification that resolved the ambiguities of the original.

Gruber holds the trademark on the Markdown name and has kept the original spec at daringfireball.net/projects/markdown mostly unchanged. Most modern markdown processors follow CommonMark or a superset of it (GitHub Flavored Markdown being the most popular).

Tools That Support Markdown

You can write markdown in any text editor, but dedicated tools give you live preview, syntax highlighting, and export options. Our markdown tools hub includes a free online editor, table generator, PDF converter, HTML converter, and formatter that all work in your browser with no signup required.

Popular desktop editors include VS Code, Obsidian, Typora, and iA Writer. For quick tasks, our browser-based tools let you start writing immediately.

Next Steps

You now know what markdown is, why people use it, and how to write a basic document. Here is where to go next:

Frequently Asked Questions