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. For consistent rendering across platforms, the CommonMark spec defines an unambiguous Markdown syntax used by GitHub, Stack Overflow, Reddit, and most modern renderers.

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.