Markdown for Beginners: Syntax, Examples & Cheat Sheet Suggested Meta Description: Learn Markdown with simple examples. Covers headings, formatting, lists, links, images, code blocks, tables, blockquotes, and common mistakes.

If you've ever written a README file, posted on a coding forum, or created documentation, you've probably encountered Markdown. Instead of wrestling with HTML tags or clunky word processor formatting, Markdown lets you use simple symbols — asterisks, hashes, and dashes — to style your text. It's fast, readable, and supported by a wide range of tools and platforms, although the exact syntax and features can vary. This guide takes you from your first line to a practical cheat sheet you can keep open in another tab.

What Is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. The goal was to let people write formatted text using plain-text symbols that remain readable even before rendering. For example, writing # Title is easier than writing <h1>Title</h1>, and the raw file is still understandable to a human.

Markdown files typically use the .md or .markdown extension. They can be opened in any text editor, and they render as formatted content on platforms that support Markdown.

Where Is Markdown Used?

Markdown is widely used in software development, but its reach extends far beyond code. Common places you'll encounter it include:

• GitHub, GitLab, and Bitbucket (README files, issues, and pull requests)
• Stack Overflow and Stack Exchange
• Documentation generators such as MkDocs, Docusaurus, and Jekyll
• Note-taking apps such as Obsidian and Bear, plus tools like Notion that support some Markdown import or conversion features
• Chat platforms such as Discord, Slack, and Telegram, each with their own Markdown-like syntax and limitations
• Jupyter Notebooks for data science and research

Important: Markdown support varies significantly between platforms. Some apps implement only a small subset, while others add their own extensions. Always test your Markdown on the platform you're targeting.

Markdown vs HTML

Markdown is simpler than HTML and easier to read as raw text. However, it doesn't replace HTML. Many Markdown processors allow you to embed raw HTML when you need something Markdown cannot express. For example, you can use the HTML <br> element for a line break where raw HTML is supported.

The key difference is that Markdown is a lightweight markup syntax, while HTML is a full markup language. A Markdown processor converts Markdown into HTML, and some processors also allow raw HTML to appear in the Markdown source.

Basic Markdown Syntax

Headings

Use # before a line to create a heading. Markdown defines six heading levels, from <h1> through <h6>. A line beginning with seven # characters is not a standard level-7 Markdown heading.

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

For ATX-style headings, a space after the # characters is required by CommonMark and is the safest form to use across Markdown implementations.

Text Formatting – Bold, Italic, and Strikethrough

• Bold: **text** or __text__ → text
• Italic: *text* or _text_ → text
• Bold + Italic: ***text*** → text
• Strikethrough (GFM extension): ~~text~~ → text

Lists

Unordered list: use -, *, or +. The - marker is common and easy to read.

- Apple
- Banana
- Cherry

Ordered list: use numbers followed by a period.

1. First step
2. Second step
3. Third step

Nested lists: indent sub-items consistently. The exact indentation rules can vary between Markdown implementations.

- Fruits
  - Apple
  - Banana
- Vegetables
  - Carrot
  - Spinach

Task Lists (GitHub Flavored Markdown)

Task lists are supported by GitHub Flavored Markdown (GFM) and some other Markdown implementations.

- [x] Write documentation
- [ ] Review pull request
- [ ] Publish release

Links

Place the link text in square brackets, followed immediately by the URL in round brackets.

[Visit Google](https://www.google.com/)

Renders as: Visit Google

You can also add an optional title:

[Google](https://www.google.com/ "Search engine")

Reference-style links are useful when you have many links or want to keep the main text clean.

[Google][google]
[Google][google]

[google]: https://www.google.com/

Images

Image syntax is similar to link syntax, but begins with an exclamation mark. The text inside the square brackets becomes the alternative text (alt text).

![A descriptive alt text](https://example.com/image.jpg)

Replace the example URL with the actual image URL. Good alt text should briefly describe the image and its purpose.

Blockquotes

Start a line with > to create a blockquote. You can also nest blockquotes and include other Markdown elements inside them.

> This is an example blockquote.
>
> It can contain multiple paragraphs.

The > character is part of the Markdown source. Markdown processors typically render it as a styled blockquote.

Code – Inline and Blocks

Inline code: wrap the text in single backticks.

Use `print("hello")` to display text.

Fenced code block: use three backticks on a separate line before and after the code. You can optionally specify a language for syntax highlighting, depending on the platform.

```python
print("Hello, world!")
```

In the example above, the triple backticks are shown literally so you can see the Markdown syntax. In an actual Markdown file, the opening and closing backticks define the code block.

Horizontal Rule

Use three or more dashes, asterisks, or underscores on a separate line.

Above the rule.

---

Below the rule.

For consistent results, place the horizontal rule on its own line with a blank line before and after it.

Tables (GitHub Flavored Markdown / Extension)

Important: Tables are not part of the original Markdown or CommonMark specification. They are supported by many Markdown implementations. GitHub Flavored Markdown (GFM), for example, supports tables, but some Markdown processors may not render them.

| Name  | Age |
|-------|-----|
| Alice | 25  |
| Bob   | 30  |

Renders as:

Line Breaks

In many Markdown implementations, a single line break does not create a visible line break in the rendered output. To force a line break, add two trailing spaces before the newline, or use the HTML <br> element when raw HTML is supported.

First line with two spaces at the end.  
Second line.

Escaping Special Characters

If you want to display a character that Markdown uses for formatting — such as * or # — you can often precede it with a backslash.

\*literal asterisk\*
\# literal hash

Markdown vs CommonMark vs GFM

There are several Markdown flavors and specifications:

• Original Markdown: The Markdown syntax described in John Gruber's original Markdown project, introduced in 2004.
• CommonMark: A standardized specification for Markdown syntax designed to define consistent parsing behavior and reduce ambiguity.
• GitHub Flavored Markdown (GFM): An extension of CommonMark with additional features such as tables, task lists, and strikethrough.

For most beginners, GFM is a practical starting point because GitHub is a common environment for learning and using Markdown. However, always check which Markdown features your target platform supports.

Complete Markdown File Example

Here is a realistic README.md example that combines several Markdown features:

# My Project

This is a **simple project** that demonstrates Markdown.

## Features

- Fast
- Easy
- Open source

## Installation

```bash
npm install

Documentation

Read the "documentation" (https://example.com/).

License

This project is open source.

This example combines headings, bold text, lists, a fenced code block, and a link in one Markdown file.

Common Markdown Mistakes

• Forgetting the space after # in headings
• Using inconsistent list indentation or markers
• Using spaces or tabs to indent paragraphs, which can trigger code blocks in some contexts
• Assuming tables work on every Markdown platform
• Confusing inline code using single backticks with fenced code blocks
• Forgetting that some platforms do not allow raw HTML
• Using Markdown features without checking whether the target platform supports them

Markdown Cheat Sheet

Final Thoughts

Markdown is one of the easiest tools to learn, but the variations between implementations can sometimes be surprising. Start with the basics — headings, bold, italic, lists, links, and code — and test your syntax on the specific platform you're using. Once you're comfortable, the cheat sheet above will help you move faster.

You don't need to memorise everything. Keep this page handy, write often, and the symbols will become second nature.

```