Markdown Syntax: The Complete Beginner's Guide

Markdown is a plain-text formatting language that turns simple symbols into styled HTML. Type # Hello and you get a heading. Wrap a word in **stars** and it turns bold. You write in readable text, and a converter renders it as a formatted document, no HTML tags and no mouse clicking through a toolbar.

This guide covers the whole syntax from scratch: headings, bold and italic, lists, links, images, code, tables, and the GitHub extras. Every rule comes with a copy-paste example. If you are learning Markdown for beginners, read top to bottom. If you just need a reminder, jump to the cheat sheet near the end.

What is Markdown and why writers and developers use it

Markdown is a lightweight markup language created by John Gruber in 2004. The idea: write formatting the way people already do in plain email (asterisks for emphasis, dashes for bullets) and let a program convert it to HTML.

So what is Markdown good for in practice? It shows up nearly everywhere text needs light formatting without a full editor. README files on GitHub and GitLab. Notes in Obsidian and Notion. Documentation sites. Chat in Slack and Discord (a subset). Static blogs like this one, where posts are .md or .mdx files.

Writers like it because it stays out of the way. You keep your hands on the keyboard and the source file reads fine even before rendering. Developers like it because plain text lives happily in Git, so you can diff it, review it, and track changes line by line. A Word document cannot do that.

How Markdown works (plain text in, formatted HTML out)

Markdown is a two-step process: you write plain text with a few symbols, and a parser converts that text into HTML. The #, *, and - characters are instructions, not decoration.

Here is the whole model in one example. This Markdown:

## Shopping list
Milk and **eggs** are the priority.

becomes this HTML:

<h2>Shopping list</h2>
<p>Milk and <strong>eggs</strong> are the priority.</p>

You never write the tags. The parser does. Different tools use different parsers (CommonMark, GitHub’s parser, marked, markdown-it), which is why the same file can render slightly differently in two apps. The core syntax below works the same everywhere. The extras in the GitHub section do not.

One rule catches every beginner: blank lines matter. A paragraph is text separated from the next block by an empty line. Press Enter once inside a paragraph and most parsers glue the lines together as if you never hit the key.

Basic syntax, headings, bold, italic, and paragraphs

Start with the four things you will use in almost every document.

Headings use #. One hash is the biggest (an H1), and each extra hash drops one level, down to six.

# Page title (H1)
## Section (H2)
### Subsection (H3)

Put a space after the hash. #Title without the space is not a heading in strict parsers, it is just literal text.

Bold and italic use asterisks. One asterisk (or underscore) is italic, two are bold, three are both.

*italic* or _italic_
**bold** or __bold__
***bold italic***

Stick with asterisks for consistency. Underscores behave oddly inside words: snake_case_variable can turn the middle into italic in some parsers, which you almost never want.

Paragraphs need a blank line between them. To force a line break without starting a new paragraph, end a line with two trailing spaces, or use a <br> tag.

First paragraph.

Second paragraph, separated by a blank line.

That blank-line rule is the single most common thing beginners miss.

Lists, links, images, and blockquotes

Lists come in two flavors. Use - (or *) for unordered bullets, and numbers for ordered lists.

- Coffee
- Tea
- Water

1. Boil water
2. Add leaves
3. Wait four minutes

Nest a list by indenting two spaces under its parent item. For ordered lists, the actual numbers do not have to be correct: write 1. on every line and the parser renumbers them for you. That makes reordering steps painless.

Blockquotes use a leading >. Stack them for nested quotes.

> This is a quote.
>
> > And a quote inside a quote.

How to use Markdown links and reference-style links

An inline link puts the visible text in square brackets and the URL in parentheses, with no space between them.

[Nelenga tools](https://nelenga.com/tools)

An image is the same syntax with a leading !. The bracketed text becomes the alt text, which matters for accessibility and SEO, so write something real, not “image1”.

![A grid of nine dots, one gold](/logo.png)

When the same URL appears several times, or a long URL clutters your sentence, use a reference-style link. You put a short label in the second set of brackets, then define it anywhere in the document.

See the [tools page][tools] and the [blog][tools] too.

[tools]: https://nelenga.com/tools

The definition never renders. It keeps your prose clean while all the labels point at one place you can update once. For a deeper look at titles, anchors, and relative paths, see the markdown links guide.

Code blocks and inline code

Inline code wraps a short snippet in single backticks, which renders in a monospace font and disables Markdown parsing inside it. Use it for filenames, function names, and values: npm install, config.json, git status.

For multiple lines, use a fenced code block: three backticks on their own line, then your code, then three backticks to close. Add a language name after the opening fence to turn on syntax highlighting.

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

If your code itself contains three backticks (for example, a Markdown tutorial like this one), open the fence with four backticks so the inner three are treated as content. The full rules for languages, indentation, and escaping live in markdown code blocks.

GitHub Flavored Markdown extras, tables, task lists, strikethrough

GitHub Flavored Markdown (GFM) adds features on top of the core syntax. These work on GitHub, GitLab, and most modern editors, but not in the strictest original parsers, so test before you rely on them elsewhere.

Tables use pipes to separate columns and a row of dashes to separate the header. The dash row also sets alignment: a colon on the left, right, or both sides controls it.

| Feature   | Core | GFM |
|:----------|:----:|----:|
| Headings  | yes  | yes |
| Tables    | no   | yes |

Tables are the fiddliest part of Markdown to write by hand, and the columns do not need to line up in the source to render correctly. If you have data in a spreadsheet already, do not retype it. Our csv-to-markdown converter turns a CSV export or a pasted spreadsheet range into a formatted table you can drop straight into a README. For hand-editing, see how to make a table in markdown and the alignment tricks in markdown table alignment.

Task lists are checkboxes, a GFM favorite for issues and to-do notes.

- [x] Write the draft
- [ ] Edit the draft
- [ ] Publish

Strikethrough uses two tildes: ~~this is crossed out~~. GFM also auto-links bare URLs, so a raw https:// address becomes clickable without brackets.

Markdown cheat sheet (printable quick reference)

Here is the whole core syntax in one block. This is the Markdown cheat sheet to keep next to you while you learn.

# H1
## H2
### H3

**bold**   *italic*   ~~strikethrough~~   `inline code`

- bullet item
1. numbered item

> blockquote

[link text](https://example.com)
![alt text](image.png)

| Col A | Col B |
|-------|-------|
| cell  | cell  |

- [x] done task
- [ ] todo task

​```lang
code block
​```

Copy that, render it in any editor, and you have seen every rule you will use ninety percent of the time.

Common beginner mistakes and how to avoid them

A few traps trip up almost everyone learning how to use Markdown:

• No space after # or -. #Heading and -item fail in strict parsers. Always add the space.
• Forgetting the blank line. Lines with no empty line between them merge into one paragraph. Blocks (lists, quotes, code) usually need a blank line before them too.
• Underscores inside words. file_name_here can italicize the middle. Use backticks for code or asterisks for emphasis.
• Unclosed code fences. Leave off the closing ``` and the rest of your document renders as code. Count your fences.
• Assuming every feature is universal. Tables, task lists, and strikethrough are GFM, not core Markdown. Check what your target platform supports.

FAQ

Is Markdown the same as HTML? No. Markdown is a shorthand that converts into HTML. It covers common formatting with far less typing, but HTML can do things Markdown cannot, like complex layouts. Most parsers also let you drop raw HTML into a Markdown file when you need it. See markdown vs html for the full comparison.

What file extension does Markdown use? Usually .md, sometimes .markdown. Variants exist too: .mdx mixes Markdown with components, and .rmd is R Markdown. They are all plain text, so any editor can open them.

Do I need special software to write Markdown? No. Any text editor works, including Notepad. Dedicated editors (Obsidian, Typora, VS Code) add a live preview so you see the rendered result as you type, which helps a lot while you are learning.

Why does my Markdown look different on GitHub than in another app? Different apps use different parsers. GitHub Flavored Markdown adds tables, task lists, and strikethrough that plain CommonMark does not render. Stick to the core syntax for anything that has to look identical everywhere.