What Is Markdown? A Plain-English Guide With Examples

Markdown is a way to format text using ordinary keyboard characters. A # at the start of a line makes a heading, **two asterisks** around a word make it bold, and a - starts a bullet list. You write plain text, and an app or website turns those symbols into formatted text. If nothing converts them, the raw text is still easy to read.

John Gruber created Markdown in 2004, with help from Aaron Swartz, so people could write for the web without typing HTML tags. Today it shows up in note apps, chat apps, code repositories, documentation sites and AI chat assistants.

What Markdown is (and isn't)

Markdown is a set of plain-text conventions plus a converter that reads them. The text you type is the source. The formatted version you see is the rendered output.

Here is a short piece of Markdown source:

# Weekend plan

Pick up the **bike** from the shop before *noon*.

- Groceries
- Laundry
- Call the landlord

Notes are on [the shop's site](https://example.com).

A Markdown app renders that as a large "Weekend plan" heading, a sentence with "bike" in bold and "noon" in italics, a three-item bullet list, and a clickable link. Open the same text in a plain editor with no Markdown support and it still reads cleanly. That readability is the whole point of the format.

Markdown files usually end in .md (sometimes .markdown). They are plain text files, so any text editor can open them.

Markdown is a markup language, not a programming language. It describes how text should be structured. It has no logic, variables or calculations.

Why people use it

• It's fast. Your hands stay on the keyboard. Typing ## is quicker than reaching for a toolbar menu.
• It's readable before it's formatted. A Markdown file still looks like a tidy note in a plain text editor, an email or a terminal.
• It's portable. A .md file isn't tied to one app. If an app shuts down or you switch tools, the text still opens anywhere.
• The habits carry over. Once you know the basics, the same symbols work on GitHub, in many note apps and in several chat tools.
• It works with version control. Plain text shows clean line-by-line changes in tools like Git, which is why developers write documentation in it.

It also has real limits:

• No fonts, colors or page layout. Markdown controls structure (headings, lists, emphasis), not design. For a brochure or a styled report, use a word processor.
• Tables are fiddly. You draw them with pipes and dashes, which gets tedious beyond a few columns.
• Images are references. In a .md file, an image is a link to a separate file or URL, not something stored inside the text.
• Not every app reads it the same way. The next section explains why.

Markdown flavors: why it looks different between apps

Gruber's original description left some edge cases open, so different tools filled the gaps differently. The variants you'll run into most:

• Original Markdown: headings, emphasis, lists, links, images, quotes and code.
• CommonMark: a stricter written specification that removes the ambiguity. Many tools follow it.
• GitHub Flavored Markdown (GFM): CommonMark plus tables, task lists (- [ ]), strikethrough (~~text~~) and automatic links.

Apps also add their own extras. Treat the basic syntax below as portable, and check an app's help pages before relying on anything fancier.

Basic Markdown syntax

These work in almost every Markdown tool. Rows marked GFM need GitHub Flavored Markdown or an app that supports the same extensions.

For a block of code, put three backticks on the line before and the line after:

```
total = price * quantity
```

A simple table (GFM) looks like this:

| Item   | Qty |
|--------|-----|
| Apples | 6   |
| Bread  | 1   |

For the full list with more examples, see our Markdown cheat sheet. Checklists have their own quirks, covered in our guide to Markdown checklist syntax.

Mistakes that trip up beginners

• No space after the symbol. In CommonMark, #Heading stays plain text. Write # Heading, with a space.
• Line breaks disappear. In standard Markdown, a single Return inside a paragraph doesn't start a new line when rendered. Leave a blank line between paragraphs. For a break inside a paragraph, end the line with two spaces. Some apps treat every Return as a break, so the same text can look different from one place to the next.
• Numbered lists renumber themselves. Many renderers use only the first number and count up from there, so 1. 1. 1. displays as 1, 2, 3. Handy when you reorder items.
• Stray asterisks or underscores. Text like file_name_v2 or 2*3*4 can accidentally turn italic in some apps. Put a backslash before the character (\*, \_) to show it literally, or wrap the text in backticks.
• Lists that run into paragraphs. Some renderers need a blank line before a list starts.

Where you can write Markdown

You don't need special software. Any plain text editor works: Notepad on Windows, or TextEdit on a Mac after you choose Format > Make Plain Text. The only difference is whether something renders it for you.

Common places that read Markdown:

• GitHub and other code hosts: README files, issues and comments (GFM).
• Developer Q&A and forums: Stack Overflow and Reddit accept Markdown in posts.
• Chat apps: Discord supports a subset, such as bold, italics and code blocks. Slack uses its own similar formatting rules, so some symbols behave differently there.
• AI chat assistants: tools like ChatGPT format their replies in Markdown, which is why answers show headings, bold text and code blocks. Copying a reply can paste the raw asterisks into apps that don't render them.
• Code editors: VS Code and most other code editors can preview .md files side by side.
• Website and documentation tools: static site generators such as Jekyll and Hugo turn folders of Markdown into websites.
• Converters: Pandoc turns Markdown into Word documents, PDFs, HTML and many other formats.
• Note apps: covered next, because they use Markdown in different ways.

How note apps use Markdown

"Supports Markdown" can mean two different things in a note app. The difference matters if you care about getting your notes out later.

Apps where your notes are Markdown

Some apps treat Markdown as the format your notes live in. You type the symbols, the app shows a formatted view, and the note itself stays Markdown text.

Obsidian is the best-known example: a Markdown note-taking app that keeps notes in local "vaults". Its 1.14 update added support for opening individual Markdown files. As of November 2026, third-party sources list the core app as free and Obsidian Sync (for syncing between devices) at $4 per user per month billed annually, or $5 monthly. This kind of app suits you if you want notes you can open in other editors, back up as ordinary files, or move to another tool without converting anything.

Apps that use Markdown as typing shortcuts

Other apps borrow Markdown's symbols as quick formatting commands, then convert them into their own format as you type. You get Markdown's speed without seeing the symbols afterward. The note isn't a .md file, though, so moving notes elsewhere depends on the app's export.

Gubb, the app we make, works this way. In a Gubb note, you type a marker at the start of a line and press Space:

The trade-off is real. Gubb stores notes in a local database on your computer, not as .md files. Its Markdown export currently writes each note's raw editor data rather than readable Markdown, and imported .md files currently open empty. If plain Markdown files are what you're after, use an app built around them, like Obsidian. Gubb fits quick capture, lists and scratch notes where you want fast formatting and don't plan to move the files around.

When an app doesn't say which kind it is

Many apps describe themselves as "Markdown" without saying how they store notes. If moving your notes later matters, look up where and in what format the app saves them, and try its export once before you commit.

Bear is a Markdown notes app for Apple devices that organizes notes with #tags and links between notes. As of November 2026, its core features are free. From November 24, 2026, Bear Pro, which adds iCloud sync between devices and per-note password protection, costs $3.99 a month or $39.99 a year. Bear runs on macOS, iOS, iPadOS and watchOS, with Bear Web in beta. There is no Windows app.

Which approach suits you

• Pick an app that keeps notes as Markdown (like Obsidian) if you want long-term notes in an open format, plan to open the same files in other editors, or keep notes in Git.
• Pick a shortcut-style app (like Gubb) if you mostly want fast formatting while you type and you're fine with the app storing your notes.
• Use a plain text editor if you just need to write a README or a quick document. Markdown needs nothing more.

For a broader look at note apps, see our roundup of the best notes apps for Mac or the Apple Notes vs Obsidian comparison.

FAQ

Is Markdown hard to learn?

No. Headings, bold, italics, lists and links cover most everyday writing, and they take a few minutes to pick up. Tables and code blocks can wait until you need them.

How do I open a .md file?

Any text editor will open it, because it's plain text. To see it formatted, open it in a Markdown-aware app, such as a code editor with a preview pane or a Markdown note app.

Why do I see asterisks and pound signs in pasted text?

The text was written in Markdown, often by an AI assistant or copied from a Markdown file, and the app you pasted into doesn't render it. Paste into a Markdown-aware app, or delete the symbols by hand.