Markdown Basics: A Complete Beginner's Guide

What Is Markdown and Why Does It Matter?

Markdown was created by John Gruber and Aaron Swartz in 2004 with one goal: let writers focus on words, not angle brackets. Instead of writing <strong>bold</strong>, you write **bold**. The raw text stays readable in any editor while a parser converts it to clean HTML for the browser.

Today Markdown is everywhere. GitHub uses it for README files and pull-request descriptions. Notion, Obsidian, and Bear use it for notes. Static site generators like Next.js, Astro, and Hugo use it for page content. Discord and Slack use a dialect of it for chat messages. Learning Markdown is one of the highest-leverage writing skills a developer, technical writer, or knowledge worker can acquire.

Throughout this guide you can paste any of the examples directly into the LiveMarkdownText editor to see them rendered in real time.

Headings (H1–H6)

Headings are created with the hash (#) character. The number of hashes determines the heading level — one hash produces an <h1>, six hashes produce an <h6>.

markdown# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Always put a space between the hashes and the heading text. Most parsers require it, and linters will flag the omission. Use a single H1 per document for the main title and nest lower levels logically — never skip from H2 to H4.

An alternative syntax uses underline-style markers on the line below the text: equals signs (===) for H1 and hyphens (---) for H2. This style is less portable and should be avoided in new documents.

Paragraphs and Line Breaks

A paragraph is simply one or more lines of consecutive text. To start a new paragraph, leave a blank line between the two blocks of text.

markdownThis is the first paragraph.

This is the second paragraph, separated by a blank line.

A single newline within a paragraph is treated as a space — it does not create a line break in the rendered output. To force a hard line break inside a paragraph, end the line with two or more spaces before pressing Enter:

markdownLine one ends with two spaces
Line two starts here on a new line.

Many editors strip trailing whitespace automatically, which can silently break intentional line breaks. As a more portable alternative, most modern parsers also accept a backslash at the end of a line:

markdownLine one ends with a backslash\
Line two starts here.

Bold, Italic, and Strikethrough

Markdown uses asterisks (*) and underscores (_) to mark up emphasis. Both delimiters produce the same output; the convention is to use asterisks for consistency.

markdown*italic* or _italic_
**bold** or __bold__
***bold and italic*** or ___bold and italic___
~~strikethrough~~ (GFM extension)

Strikethrough (~~text~~) is a GitHub Flavored Markdown extension and may not render on older or minimal parsers. Inline formatting can be nested: you can bold part of an italic phrase by mixing delimiters: *This is _mixed_ emphasis*.

Links

Inline links use square brackets for the link text and parentheses for the URL:

markdown[Visit LiveMarkdownText](https://livemarkdowntext.com)
[Relative page](/learn)
[Link with title](https://example.com "Hover tooltip text")

For long documents with many links to the same URL, reference-style links keep the prose readable by separating the URL definitions to the bottom of the document:

markdownRead the [official specification][spec] for details.

[spec]: https://spec.commonmark.org

In GitHub Flavored Markdown, bare URLs are auto-linked without any markup: https://example.com becomes a clickable link automatically.

Images

Image syntax mirrors link syntax but with a leading exclamation mark. The text inside the square brackets becomes the alt attribute — always provide a descriptive value for accessibility:

markdown![A golden retriever sitting in a park](./dog.jpg)
![Logo](https://example.com/logo.png "Optional title")

Markdown itself has no syntax for controlling image dimensions. If you need to set a width or height, drop into raw HTML: <img src="./photo.jpg" alt="Photo" width="400">. Most Markdown parsers pass raw HTML through to the output unchanged.

Ordered and Unordered Lists

Unordered lists

Use a hyphen (-), asterisk (*), or plus sign (+) followed by a space to create unordered list items. Hyphens are the most common convention:

markdown- Apples
- Bananas
- Cherries

Ordered lists

Ordered lists use a number followed by a period and a space. Interestingly, the actual numbers do not matter — the rendered output uses consecutive integers starting from the first number in the list:

markdown1. First item
2. Second item
3. Third item

Nested lists

Indent sub-items by two or four spaces (or one tab) to create nested lists. You can mix ordered and unordered at different levels:

markdown- Fruit
  - Apples
  - Bananas
- Vegetables
  1. Carrots
  2. Peas

Task lists (GFM)

GitHub Flavored Markdown adds task-list checkboxes using - [ ] for unchecked and - [x] for checked:

markdown- [x] Write the introduction
- [x] Add code examples
- [ ] Publish the article

Blockquotes

Prefix a line with a greater-than sign (>) to create a blockquote. Blockquotes can span multiple paragraphs and can be nested:

markdown> This is a blockquote.
> It can span multiple lines.
>
> And even multiple paragraphs.

> Outer blockquote
>
> > Nested inner blockquote

Blockquotes support all other Markdown formatting inside them — you can include headings, lists, code, and emphasis within a blockquote block.

Code — Inline and Fenced Blocks

Inline code

Wrap a short snippet in single backticks to render it as inline code. This is ideal for variable names, function calls, or short commands within a sentence:

markdownUse the `console.log()` function to debug your JavaScript.

Fenced code blocks

For multi-line code, open and close the block with three backticks (```) on their own lines. Add a language identifier immediately after the opening fence to enable syntax highlighting:

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

console.log(greet("world"));
```

Common language identifiers include javascript, typescript, python, bash, css, html, json, and markdown. The identifier is case-insensitive.

Indented code blocks

The original Markdown spec also treats lines indented by four spaces (or one tab) as code. This style is supported but less convenient than fenced blocks because it does not support language identifiers.

Horizontal Rules

A horizontal rule (<hr>) visually separates sections of a document. Create one with three or more hyphens, asterisks, or underscores on their own line. Spaces between the characters are optional:

markdown---

***

___

Be careful: three hyphens (---) directly under a line of text are interpreted as a setext-style H2 heading, not a horizontal rule. Always leave a blank line above a horizontal rule.

Escaping Characters

When you need to display a literal character that Markdown would otherwise interpret as formatting syntax, prefix it with a backslash:

markdown*This text is not italic*
# This is not a heading
[This is not a link]

The following characters can be escaped with a backslash:

markdown\ ` * _ {} [] () # + - . !

Inside a fenced code block you never need to escape — everything is treated as literal text.

Tables (GFM Bonus)

Although not part of the original Markdown spec, pipe tables are available in GitHub Flavored Markdown and supported by nearly every modern parser. Columns are separated by pipe characters (|) and the header row is followed by a separator row of hyphens. Colons in the separator control column alignment:

markdown| Element     | Syntax        | Output              |
|-------------|:-------------:|--------------------:|
| Bold        | **text**      | **bold text**       |
| Italic      | *text*        | *italic text*       |
| Inline code | `code`      | `code`            |

The colon on the left side of the dashes aligns left, on the right aligns right, and colons on both sides center the column. Pipe characters at the very start and end of each row are optional but recommended for readability.

Practical Tips for Better Markdown

• Use a live preview. The LiveMarkdownText editor renders your Markdown in real time so you catch formatting mistakes immediately.
• Blank lines are your friend. When in doubt, add a blank line before and after headings, lists, blockquotes, and code blocks to avoid unexpected parsing behaviour.
• Stick to one delimiter style. Choose asterisks or underscores for emphasis and hyphens for list bullets — then be consistent throughout the document.
• Keep lines short. Many style guides recommend wrapping prose at 80–120 characters. Short lines produce cleaner git diffs and are easier to review.
• Use fenced code blocks over indented ones. Fenced blocks with a language identifier enable syntax highlighting and are unambiguous even when the surrounding context changes.
• Write meaningful alt text. Screen readers and search engines both rely on image alt text. Describe the content of the image, not just its file name.

What to Learn Next

You now know the building blocks of Markdown. Here is a suggested learning path:

1. GitHub Flavored Markdown (GFM) — tables, task lists, strikethrough, autolinks, and fenced code blocks with syntax highlighting.
2. Mastering Markdown Tables — alignment, complex data, and common formatting pitfalls.
3. Writing Technical Documentation in Markdown — README best practices, API docs, and wikis.

Frequently Asked Questions