Markdown in Plain Terms

Markdown is a way to format text using simple characters you already have on your keyboard. Instead of clicking a bold button in a toolbar, you wrap a word in asterisks. Instead of selecting a heading size from a dropdown, you type a hash symbol at the start of a line. The result is plain text that's easy to read on its own, but that any markdown aware tool can render into a properly formatted document.

John Gruber created markdown in 2004 with one goal: make it easy to write formatted text that's still readable as plain text. He succeeded. Nearly twenty years later, markdown is used everywhere: GitHub, Reddit, Notion, Slack, countless blogs, academic papers, technical documentation, and personal notes.

If you've ever typed **bold** in a chat app and seen it turn bold, you've already used markdown.

Why People Use Markdown

There are plenty of ways to format text. Word processors, rich text editors, HTML. So why bother with markdown? A few reasons:

• It's plain text. Your markdown files are just text files. They open in any text editor on any operating system. They'll be readable in ten years, in fifty years, forever. Try opening a WordPerfect document from 1995 and you'll appreciate this.
• It's portable. Markdown looks the same everywhere. Write it on your Mac, read it on someone else's phone. No formatting gets lost because there's no proprietary format to get corrupted.
• It's fast. Once you learn the syntax (which takes about ten minutes), you can format text without ever moving your hands from the keyboard. No reaching for the mouse, no hunting through toolbars.
• It's convertible. Markdown can be turned into HTML, PDF, Word documents, slides, and more. Write once, export to whatever format you need.

Who Uses Markdown

The Basic Syntax

Here's everything you need to start writing markdown. Each example shows what you type and what it looks like when rendered.

Headings

Use hash symbols (#) to create headings. More hashes mean smaller headings.

Headings go up to six levels (######), though you'll rarely need more than three. They structure your document and create a hierarchy, which is why tools like Indent can auto generate a document outline from them.

Bold and Italic

Wrap text in asterisks to make it bold or italic.

Two asterisks for bold, one for italic, three for both. You can also use underscores (_) instead of asterisks, but asterisks are more common.

Links

Links use a combination of square brackets (for the text) and parentheses (for the URL).

The text in square brackets is what people see. The URL in parentheses is where the link goes. Once you've typed a few of these, it becomes second nature.

Lists

For unordered lists, start each line with a dash, plus sign, or asterisk. For ordered lists, use numbers followed by periods.

You can nest lists by indenting items with spaces or tabs. Most renderers handle this gracefully.

Code

For inline code (within a sentence), wrap it in backticks. For code blocks (multiple lines), use three backticks before and after.

function greet(name) {
  return `Hello, ${name}!`;
}

Code blocks are one of markdown's most popular features, especially among developers. The content inside a code block is displayed exactly as you type it, with no formatting applied.

Blockquotes

Start a line with a greater than sign (>) to create a blockquote.

Images

Images work like links, but with an exclamation mark in front.

Horizontal Rules

Three or more dashes, asterisks, or underscores on their own line create a horizontal divider.

That's Most of It

Seriously. Headings, bold, italic, links, lists, code, blockquotes, images, and horizontal rules. That covers 95% of what you'll ever need to write in markdown. There are a few more features in various markdown "flavors" (tables, task lists, footnotes), but the basics above will carry you through almost any document.

The beauty of markdown is that it takes about ten minutes to learn and you never forget it. The syntax is intuitive enough that after using it for a day, it feels like second nature.

Markdown Flavors

Markdown's original specification was intentionally minimal. Over time, different platforms and tools have added their own extensions. You'll sometimes hear these called "flavors."

• GitHub Flavored Markdown (GFM) adds tables, task lists, strikethrough, and auto linked URLs. It's the most commonly used extended flavor.
• CommonMark is a standardized specification that resolves ambiguities in the original markdown. Most modern tools follow CommonMark.
• MultiMarkdown adds footnotes, citations, tables, and metadata. Popular in academic writing.

The core syntax we covered above works in all flavors. The differences are in the extras. If you learn the basics, you can write markdown that works anywhere.

The Best Way to Learn: Write and See

The fastest way to learn markdown is to type it and immediately see what it produces. This is exactly what a split view markdown editor gives you: type on the left, see the result on the right. You learn the connection between syntax and output in real time.

Indent is designed for exactly this. Open the app, create a new document, switch to split view, and start typing. As you write # Hello, you'll see a heading appear on the right. As you wrap text in **asterisks**, you'll see it go bold. The feedback loop is instant, and that makes learning fast.

Why Markdown Instead of a Word Processor

Word processors like Google Docs or Microsoft Word are perfectly good tools. You don't need to switch to markdown. But there are reasons many people choose to:

• Plain text lasts forever. A .md file created today will be readable on any computer in any decade. The same can't be said for every proprietary format.
• No vendor lock in. Your markdown files aren't tied to any specific app. Move between editors freely. Your content goes with you.
• Faster writing. Formatting with keyboard characters is faster than moving your hands to a toolbar. Once the syntax is muscle memory, you'll notice the difference.
• Version control friendly. Because markdown is plain text, it works beautifully with version control systems like Git. You can track every change to every line of a document.
• Focused writing. No font menus, no color pickers, no template galleries. Just your words and a few simple characters to format them. There's less to distract you.

That said, markdown isn't the right tool for everything. Complex documents with precise layout requirements (think resumes with multiple columns, or brochures) are still better suited to a design tool or word processor. Markdown excels at structured, text heavy documents.

Where Markdown Is Used

You might be surprised how many places already use markdown:

• GitHub and GitLab use markdown for README files, issue descriptions, pull request comments, and wikis.
• Reddit uses markdown for comments and posts.
• Slack and Discord support markdown formatting in messages.
• Notion, Obsidian, and Bear use markdown as their underlying format.
• Static site generators like Hugo, Jekyll, and Gatsby use markdown for content.
• Jupyter notebooks use markdown for text cells alongside code.

Learning markdown isn't learning a niche skill. It's learning a format that's already woven into the tools you probably use every day.

Getting Started

Here's the quickest path from "I've never used markdown" to "I'm comfortable with it":

1. Get a markdown editor with a preview. Indent is free and shows you the rendered output next to your text. This instant feedback is the fastest teacher.
2. Start with headings and paragraphs. Just write normally, but use # for headings. That alone gives you a structured document.
3. Add bold and italic. Wrap important words in **double asterisks** or *single asterisks*. You'll start doing this instinctively within a day.
4. Try lists. Start a line with - for a bullet point. Start with 1. for a numbered list. That covers most note taking needs.
5. Learn links and code when you need them. The link syntax [text](url) and the code syntax (backticks) are easy to look up when the moment comes. No need to memorize them upfront.

Within a week of casual use, you'll have the whole syntax committed to memory. It's genuinely that simple.

Try It in Indent

Indent is a free markdown editor for Mac, iPhone, and iPad. It has a split view that shows your markdown and its rendered output side by side, which makes it an ideal learning environment. Every feature is free with no subscription, no account, and no time limit.

Download it from the App Store, create a new document, and try typing the examples from this guide. You'll be writing markdown in no time.