Back to blog

Markdown Cheat Sheet: Syntax, Examples, and Tips

Need a markdown cheat sheet? Learn syntax, examples, and tips for headings, lists, links, code blocks, tables, and more—fast and easy.

Introduction

Markdown is a lightweight way to format plain text with simple symbols, making it useful for notes, README files, documentation, and technical writing. A markdown cheat sheet is a quick reference that shows the most common Markdown syntax in one place so you can write and troubleshoot faster.

Markdown was created by John Gruber, with Aaron Swartz helping shape the original design. It is designed to be readable as plain text and easy to convert into HTML through a Markdown parser.

This guide answers the most common questions: what Markdown is, how to use it, how to write headings, bold and italic text, lists, links, images, code blocks, tables, line breaks, and escaped characters, plus how Markdown differs from HTML and where features vary across platforms.

What Is Markdown?

Markdown is a lightweight markup language that lets you write formatted content in plain text. Instead of using lots of HTML tags, you use simple symbols such as #, *, [](), and backticks. A Markdown parser converts that text into HTML or another display format.

Compared with HTML, Markdown is faster to write and easier to scan. HTML is more explicit and gives you finer control over layout and structure, which is why many teams use Markdown for drafting and HTML only when they need precise formatting.

You will see Markdown in documentation, technical writing, README files, blogs, knowledge bases, and note-taking tools.

How Do You Use Markdown?

You use Markdown by typing plain text with Markdown syntax and then previewing it in the tool you are using. In practice, that means:

  • adding headings with #
  • making text bold or italic with ** and *
  • creating lists with -, *, or 1.
  • adding links with [text](url)
  • inserting images with ![alt text](image-url)
  • writing code with inline code or fenced code blocks

Because Markdown support varies, always preview your content in the destination platform. GitHub, GitLab, Obsidian, VS Code, Notion, WordPress.com, and Squarespace all support Markdown in different ways, but not every feature works the same everywhere.

How Do You Make Headings in Markdown?

Use one to six hash symbols at the start of a line:

# H1
## H2
### H3
#### H4
##### H5
###### H6

Use headings to organize content clearly. In most documentation and technical writing workflows, one H1 is enough for the page title, and H2s and H3s handle the main sections and subsections.

How Do You Bold Text in Markdown?

Use double asterisks or double underscores:

**bold text**
__bold text__

Use bold text for emphasis, labels, or key terms. Avoid overusing it, because too much bolding makes text harder to scan.

How Do You Italicize Text in Markdown?

Use single asterisks or single underscores:

*italic text*
_italic text_

Italic text works well for emphasis, titles, or subtle distinctions. If you need bold and italic together, many Markdown parsers support ***bold and italic***.

How Do You Create Lists in Markdown?

Use hyphens, asterisks, or plus signs for unordered lists, and numbers for ordered lists:

- Item one
- Item two
  - Nested item

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

For task lists in GitHub Flavored Markdown, use checkboxes:

- [ ] Open issue
- [x] Fix bug

Task lists are supported in GitHub and GitLab, and they are also common in Obsidian. Support in other tools may vary.

How Do You Add Links in Markdown?

Use the standard link format:

[Markdown style guide](https://docsfordevs.com/blog/markdown-style-guide-for-teams)

If you want to reuse a URL, reference links can keep the text cleaner:

[Read the guide][style-guide]

[style-guide]: https://docsfordevs.com/blog/markdown-style-guide-for-teams

Descriptive link text is better for accessibility and easier to scan in documentation.

How Do You Insert Images in Markdown?

Use an exclamation mark, alt text, and the image URL:

![Diagram of heading levels](image-url "Heading hierarchy")

Alt text matters for accessibility and helps readers understand the image if it does not load. In technical writing, use alt text that explains the purpose of the image, not just what it looks like.

How Do You Write Code Blocks in Markdown?

Use inline code for short snippets and fenced code blocks for longer examples:

Use `git status` to check your repository.

git status
git add .
git commit -m "Update docs"

Fenced code blocks are especially useful in README files and documentation because they preserve formatting. Adding a language label such as bash, js, or html enables syntax highlighting in many tools, including GitHub, GitLab, and VS Code.

How Do You Make Tables in Markdown?

Use pipes and hyphens to build tables:

| Syntax | Meaning |
|---|---|
| `#` | Heading |
| `**text**` | Bold text |
| `*text*` | Italic text |

Some Markdown parsers also support alignment with colons:

| Left | Center | Right |
|:---|:---:|---:|
| A | B | C |

Tables are part of GitHub Flavored Markdown, but support can differ in other platforms.

How Do Line Breaks Work in Markdown?

A blank line creates a new paragraph. A single line break inside a paragraph is handled differently depending on the parser. In many Markdown flavors, you can force a line break by ending a line with two spaces or by using <br> when the platform allows HTML.

For example:

First line  
Second line

Line breaks are one of the most common sources of confusion because some editors collapse them while others preserve them.

How Do You Escape Characters in Markdown?

Use a backslash before characters that would otherwise be interpreted as formatting:

\* \_ \[ \] \( \) \# \`

Escaping is useful when you want to show literal symbols in plain text, such as a filename, a command, or a piece of code that includes Markdown characters.

What Is the Difference Between Markdown and HTML?

Markdown is simpler and faster for writing content in plain text. HTML is more verbose but gives you more control over structure and presentation.

Use Markdown for drafting, documentation, README files, and technical writing. Use HTML when you need precise control, custom components, or features that Markdown does not support consistently.

What Is GitHub Flavored Markdown?

GitHub Flavored Markdown, often called GFM, is a Markdown variant used by GitHub and supported in many other tools. It adds features such as tables, task lists, strikethrough, and better handling of code blocks.

GFM is useful for collaborative documentation because it matches how many teams already write in GitHub repositories and README files.

Which Markdown Features Are Not Supported Everywhere?

Basic Markdown is widely supported, but extended features vary. Common examples include:

  • task lists
  • tables
  • footnotes
  • callouts
  • strikethrough
  • embedded HTML

Obsidian supports many advanced note-taking features, including callouts and footnotes. GitHub and GitLab support task lists and tables. Notion supports a Markdown-like editing experience, but it is not a full CommonMark implementation. WordPress.com and Squarespace usually handle basic formatting well, but advanced syntax may be limited or converted differently.

Why Is My Markdown Not Rendering Correctly?

When Markdown does not render correctly, the most common causes are:

  • missing blank lines
  • incorrect indentation in nested lists
  • forgetting the space after a list marker
  • using the wrong heading level
  • failing to escape special characters
  • expecting a feature the platform does not support

If the syntax looks correct, test the content in another Markdown parser or preview pane. That helps you determine whether the problem is the Markdown itself or the platform.

What Are the Most Common Markdown Mistakes?

The most common mistakes are:

  • using too many heading levels without a clear structure
  • mixing tabs and spaces in lists or code blocks
  • forgetting alt text for images
  • using raw HTML when Markdown would be simpler
  • assuming every platform supports the same features
  • overusing bold, italics, or inline code

A good markdown cheat sheet should help you avoid these problems by showing the correct syntax and the limits of each platform.

How Can I Use Markdown in Obsidian, GitHub, or WordPress?

In Obsidian, Markdown is the core editing format, so you can use headings, lists, links, tables, callouts, and footnotes directly in notes.

In GitHub, Markdown is commonly used in README files, issues, pull requests, and documentation. GitHub Flavored Markdown supports task lists, tables, blockquotes, inline code, and fenced code blocks.

In WordPress.com, Markdown support depends on the editor and setup, so always preview the post before publishing. Squarespace also supports basic formatting, but advanced Markdown features may not behave the same way as they do in GitHub or Obsidian.

Quick Markdown Cheat Sheet

Headings

# H1
## H2
### H3

Emphasis

**bold**
*italic*

Lists

- Unordered item
1. Ordered item
- [ ] Task list item

Links and Images

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

Code

`inline code`

```js
console.log('Hello');


### Tables

```md
| Column 1 | Column 2 |
|---|---|
| A | B |

Blockquotes

> This is a blockquote.

Escaping

\*literal asterisk\*

Best Practices for a Markdown Cheat Sheet

Keep your syntax consistent, use descriptive links, add meaningful alt text, and choose the simplest formatting that works across your platform. For team documentation, pair this guide with a Markdown style guide, a documentation template, and README best practices.

Markdown is most effective when it stays readable in plain text and predictable across tools. That is why a good markdown cheat sheet is useful: it gives you a compact reference for writing, editing, and troubleshooting content without relying on guesswork.