What Is Markdown? A Complete Beginner-to-Practical Syntax Guide

When you open a README, write a GitHub issue, or bold some text in your notes app, you are probably using Markdown. Markdown is a lightweight markup language that lets you format plain text with a few simple symbols while keeping the source itself readable. Designed by John Gruber in 2004, its goal was clear: people should be able to read the source text as comfortably as the rendered page. In this guide we gather everything you need to learn Markdown from scratch, with practical examples and no memorization required.

Where Is Markdown Used?

Markdown is now the shared language of the software and content worlds. The places you'll meet it most often:

• GitHub / GitLab: READMEs, issues, pull request descriptions, and wiki pages.
• Documentation: Tools like Docusaurus, MkDocs, and GitBook build sites from Markdown.
• Static site generators: Next.js, Hugo, Jekyll, and Astro store blog posts as Markdown.
• Note apps: Obsidian, Notion, Bear, and Joplin are Markdown-based.
• Chat and forums: Slack, Discord, Reddit, and Stack Overflow support a subset of Markdown.

Learning a single syntax and reusing it across dozens of platforms is what makes Markdown so valuable.

Core Syntax

Below are the most common elements, with both the source text and a description of how each looks on screen.

Headings

Put # at the start of a line; more hashes mean a smaller heading (# is largest, ###### smallest).

# First-Level Heading
## Second-Level Heading
### Third-Level Heading

Result: graduated headings from large to small, exactly like the ones in this article. Always put a space between the # and your text.

Bold, Italic, and Strikethrough

**bold text**
*italic text*
***bold and italic***
~~strikethrough~~

Result: renders as bold text, italic text, both at once, and struck through. You can also use _underscores_ for italics.

Lists

Use -, *, or + for unordered lists and 1. for ordered ones. Indent by two or four spaces to nest.

- Apple
- Pear
  - Green pear
  - Red pear
- Cherry

1. Boil the water
2. Steep the tea
3. Serve

Result: you get bulleted and numbered lists; indented items nest one level deeper. Even if you write 1. on every line of an ordered list, the browser numbers them automatically.

Links and Images

[MagmaNex Tools](https://magmanex.com/en/tools/)
![Logo description](https://magmanex.com/logo.png)

Result: the first is a clickable link, the second (because of the leading !) is an image embedded into the page. The text in square brackets also serves as the image's alt text.

Blockquotes, Inline Code, and Horizontal Rules

> This is a quote.
> It can span multiple lines.

Run it with `npm install`.

---

Result: lines starting with > become an indented quote block; text in backticks renders as one-line code; and --- becomes a horizontal rule dividing the page.

Code Blocks

For multi-line code, use a fenced code block with three backticks, and name the language to get syntax highlighting.

```python
def greet(name):
    return f"Hello {name}"
```

Result: you get a monospaced code box that preserves whitespace and colorizes the code according to its language.

Quick Cheat-Sheet Table

Tables in Markdown

Tables use pipes (|) to separate columns, and a row of dashes to mark the header. Colons set the alignment.

| Product  | Price | Stock |
| :------- | ----: | :---: |
| Keyboard |   450 |  Yes  |
| Mouse    |   200 |  No   |

Result: a bold header row with columns aligned left (:---), right (---:), or centered (:---:). The cells don't have to line up perfectly in the source; a single | is enough.

Task Lists and GFM

GitHub-Flavored Markdown (GFM) adds practical extensions to standard Markdown. The most beloved is the task list:

- [x] Finish the design
- [ ] Write the tests
- [ ] Ship it

Result: checkable boxes appear; [x] is checked, [ ] is empty. GFM also supports tables, strikethrough, automatic link detection, and syntax highlighting like ```diff. Keep in mind that platforms such as Slack or Discord don't support every element (images, for instance), so knowing your target's dialect matters.

Common Mistakes and Tips

• Leave blank lines: Without a blank line before and after a heading, list, or code block, most parsers won't interpret it correctly. This is the single most common mistake.
• Escape special characters: To show characters like *, _, #, or ` as literal text, put a backslash in front: \*star\* renders as *star*.
• Hard line breaks: Markdown does not treat a single Enter as a new paragraph. To break to a new line within the same paragraph, end the line with two spaces, or leave a blank line to start a new paragraph.
• Keep list indentation consistent: Mixing space counts (like 3 spaces) in nested lists produces surprising results; stick to 2 or 4.
• Escape pipes in tables: To show a literal | inside a cell, write \|.

How to Preview and Convert

Seeing the result instantly makes writing Markdown much easier. To write and get a live preview, use our Markdown editor. To embed your writing into a web page, get clean output with the Markdown to HTML converter; and if you're tired of writing tables by hand, build tidy ones in a few clicks with the Markdown table generator. Going the other way, try the HTML to Markdown converter to turn existing HTML into Markdown.

The beauty of Markdown is that it takes about half an hour to learn but pays back in productivity for years. After writing a few examples, the syntax settles into your fingers and you'll never reach for a formatting menu again.