Markdown for beginners: the 15-minute guide

This Markdown for beginners guide covers everything you need in about 15 minutes. Markdown is a way to format plain text using a few simple symbols, like # for a heading or ** for bold. You write in regular text, add small marks, and a Markdown app turns those marks into formatted output. Below is what it is, why it shows up everywhere now, and the handful of rules you actually need.

There are maybe ten things to remember, and you'll use five of them constantly.

What is Markdown, exactly?

Markdown is a lightweight markup language. "Markup" means you mark up plain text with symbols that describe structure: this line is a heading, this word is bold, these lines are a list. A Markdown editor reads those symbols and renders them as styled text.

The key idea is that the file stays plain text. Open a Markdown file (.md) in any text editor and you'll see readable words, not a tangle of code. Compare that to a Word document, which is a packaged format you can only open in software that understands it. With Markdown, the raw file is already readable.

That plain-text foundation is what makes Markdown easy to trust: the file is the document, and nothing is hidden.

Why is Markdown everywhere now?

Markdown started in 2004 as a way to write web content without typing HTML. It spread because it's fast to write and easy to read, even as raw text.

Today you'll find it in:

• GitHub and GitLab, where every README and issue is Markdown.
• Chat and docs tools like Slack, Discord, and Reddit, which use Markdown-style formatting.
• Note apps like Obsidian and Logseq, which store notes as .md files, and Apioni, whose web app is a block editor with plain Markdown underneath.
• AI assistants like ChatGPT and Claude, which return answers formatted in Markdown by default.

That last one matters most for note-takers, given how much AI output people now paste into their notes. When an assistant gives you a structured answer with headings, bold terms, and bullet lists, it's almost always writing Markdown under the hood. If you can read and edit Markdown, you can drop a long answer straight into your notes and fix the formatting in seconds instead of rebuilding it. For the spots that usually break and how to fix them, see how to clean up AI Markdown.

How do you write headings, bold, and italic?

Start with the three you'll use most. For each one, the gray box shows the raw text you type, followed by what it becomes once an editor renders it.

Headings use # signs. One # is the biggest heading; more # signs make smaller ones.

# Big heading
## Medium heading
### Smaller heading

Bold and italic wrap text in asterisks. Two asterisks make a word bold, one makes it italic:

This is **bold** and this is *italic*.

When an editor renders that line, the words between the asterisks turn bold and italic, and the asterisks themselves vanish. The pattern is consistent: you surround the text you want to emphasize, the symbols do their job, and they disappear from the styled view. A live-preview editor shows this as you type, so the formatting appears in place. Many editors also hide the symbols once a line is done and reveal them again when you click back in to edit.

How do you make lists?

Lists come in two patterns: bullets and numbers.

For a bullet list, start each line with a dash and a space:

- Milk
- Bread
- Coffee

For a numbered list, start each line with a number, a period, and a space:

1. Preheat the oven
2. Mix the batter
3. Bake for 25 minutes

You can nest items by indenting with two spaces before the dash. Most editors add the indentation when you press Tab. One handy detail: in a numbered list, the numbers you type don't have to be right. Write 1. on every line and the renderer counts them for you.

How do you add links and images?

Links and images use square brackets and parentheses, and the two are nearly identical.

A link wraps the visible text in square brackets, then the address in parentheses:

Read the [Apioni pricing page](/pricing) for details.

An image is the same, with an exclamation mark in front. The bracket text becomes the alt text, a description used by screen readers and shown if the image fails to load:

![A photo of my desk](desk.jpg)

That's the whole pattern. If you can write a link, you can write an image; just add the !. One caveat worth knowing early: the part in parentheses has to point to where the image actually lives. A bare name like desk.jpg only works if the image sits in the same folder as your note, and it can break if you move the note. When in doubt, use a full path or a complete web URL so the image still loads.

How do you write code, quotes, and tables?

These three round out the everyday set.

For a short bit of code inside a sentence, wrap it in single backticks. For a whole block of code, use three backticks on their own lines above and below:

```
function hello() {
  return "hi";
}
```

For a quote, start the line with a >:

> This line is quoted.

Tables use pipes (|) to separate columns and a row of dashes to mark the header:

| Item   | Price |
| ------ | ----- |
| Coffee | $4    |
| Tea    | $3    |

Tables are the one piece of Markdown that looks fiddly in raw form and clean once rendered. Code blocks and tables are also where Markdown apps differ most, so it's worth seeing how they behave. There's a full walkthrough in our tables, code, and Mermaid guide.

Markdown for beginners: the cheat sheet

Here's the core syntax in one place. Keep it open while you practice.

You want	You type	Result
Heading	# Title	A large heading
Bold	**word**	word
Italic	*word*	word
Bullet list	- item	A bulleted line
Numbered list	1. item	A numbered line
Link	[text](url)	A clickable link
Image		An embedded image
Inline code	`code`	Monospaced text
Quote	> text	An indented quote
Horizontal line	---	A divider

If you remember the first six rows, you can format almost anything you write day to day. The rest you'll pick up the first time you need them.

What Markdown doesn't do (and why that's fine)

Markdown is deliberately small. It has no font picker, no text colors, no precise layout control, and no page margins. That's the point. It handles structure and emphasis, not visual design.

A few honest trade-offs:

• Flavors differ. Tables, checkboxes, and footnotes aren't in the original spec. Most modern apps support them through "GitHub Flavored Markdown," but a very old or minimal tool might not.
• Complex layouts need more. If you need columns or exact positioning, Markdown isn't the tool. Many writers drop in a little HTML for those rare cases, since most renderers allow it.
• It's not WYSIWYG by default. You write symbols, not styled text. Live-preview editors smooth this over, but it's a different feel from a word processor.

For notes, documentation, and drafts, that small feature set is an advantage. With fewer formatting options to manage, your attention stays on the words instead of how they look.

Where should you practice?

The fastest way to learn Markdown is to write some. Pick a tool that shows you the rendered result as you go, then type out a heading, a bold word, a list, and a table from the cheat sheet above. Markdown is a shared convention, so what you learn here carries over: extras like tables, checkboxes, and footnotes depend on the flavor a tool supports, but the core syntax works in almost every Markdown editor.

That portability is a big reason Markdown has lasted more than twenty years. To learn why AI assistants answer in Markdown, see why LLMs speak Markdown.

If you want somewhere to practice, try Apioni: on the web it is a block editor that accepts Markdown. Type # or - and a space at the start of a line and it becomes a heading or a bullet; paste a Markdown draft and it arrives as headings, lists, tables, and code blocks. In Apioni your notes sync to your account, and you can export a note or everything as Markdown files or an Obsidian vault.