Markdown Guide for Beginners: Syntax, Tips & Tools

What Is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. It lets you add formatting — headings, bold, links, code blocks — using simple plain-text syntax. It's designed to be readable even without rendering.

Try writing Markdown live with our free Markdown Previewer — type on the left, see the rendered output on the right.

Essential Markdown Syntax

Headings

Use # symbols for headings. More # marks mean smaller headings:

# Heading 1
## Heading 2
### Heading 3

Text Formatting

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

Links and Images

[Link text](https://example.com)
![Alt text for image](image-url.jpg)

Lists

- Unordered item 1
- Unordered item 2

1. Ordered item 1
2. Ordered item 2

Code

Use backticks for inline code and triple backticks for code blocks:

Inline `code` looks like this.

```javascript
function hello() {
  console.log("Hello, world!");
}
```

Blockquotes

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

Tables

| Header 1 | Header 2 |
| -------- | -------- |
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |

Horizontal Rule

---

Where Markdown Is Used

• GitHub: README files, issues, pull requests, and comments
• Documentation: Most static site generators (Docusaurus, MkDocs, Jekyll)
• Note-taking: Obsidian, Notion, Bear, and many others
• Messaging: Discord, Slack, and Reddit support Markdown formatting
• Blogging: Many CMS platforms support Markdown for writing posts

Tips for Writing Better Markdown

• Leave a blank line before and after headings, lists, and code blocks
• Use reference-style links for documents with many URLs
• Preview your Markdown before publishing to catch formatting issues
• Use descriptive alt text for images for accessibility
• Indent nested lists with two or four spaces consistently

Markdown Flavors

Different platforms extend standard Markdown with extra features:

• GitHub Flavored Markdown (GFM): Adds task lists, tables, and autolinked URLs
• CommonMark: A strict, unambiguous specification of standard Markdown
• MDX: Lets you embed React components inside Markdown files

The best way to learn Markdown is to practice. Open our free Markdown Previewer and start writing — you'll see results instantly.

Writing for the web? Check your content's readability with our Readability Score tool, or count words with the Word Counter.