How to Format Markdown — A Visual Cheatsheet With Examples

Markdown is the universal plain-text format for writing on the web. Every README, every GitHub issue, every blog post, every Notion page, and most documentation is written in Markdown. It is small, fast to type, readable as plain text, and renders to clean HTML in any renderer.

This is a visual cheatsheet: every common element shown side by side as source and rendered output. If you want to convert a snippet quickly, the Uttir Markdown to HTML tool renders your text in your browser, with no upload.

The 60-second version

If you have used Markdown before, here is everything that matters in one block:

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

**bold** and *italic* and code in backticks

- bullet
- list

1. numbered
2. list

[link text](https://example.com)

![alt text](image-url.png)

> blockquote

fenced code block with three backticks above and below

That is 80% of what most people use. The rest of this post is the other 20% — the edge cases, the subtle differences between renderers, and the patterns that come up in real writing.

Headings

Headings are # through ###### for H1 through H6. The space after the # is required.

Markdown	Output
# Heading 1	Heading 1 (largest)
## Heading 2	Heading 2
### Heading 3	Heading 3
#### Heading 4	Heading 4
##### Heading 5	Heading 5
###### Heading 6	Heading 6 (smallest)

Most documents use H1 for the title, H2 for the main sections, and H3 for subsections. H4 and below are rare. A clean document with H1 → H2 → H3 is much more readable than a document that uses every level.

You can also use a row of === for H1 and a row of --- for H2 (Setext-style), but the # syntax is more common and easier to read.

Emphasis

Bold and italic use * or _ as the marker. One for italic, two for bold, three for bold-italic.

Markdown	Output
*italic*	italic
_italic_	italic
**bold**	bold
__bold__	bold
***bold italic***	bold italic
~~strikethrough~~	strikethrough (GFM extension)

The * and _ versions are equivalent. Pick one and use it consistently. * is more common in technical writing.

The strikethrough syntax (~~text~~) is a GitHub Flavored Markdown (GFM) extension. Most renderers support it; some do not.

Lists

Unordered lists use -, *, or + as the marker. All three are equivalent. Numbered lists use digits followed by a period.

- First item
- Second item
- Third item

1. First
2. Second
3. Third

Renders as:

• First item
• Second item
• Third item

1. First
2. Second
3. Third

The actual numbers do not matter — the renderer renumbers based on order. So 1. ... 1. ... 1. renders as a numbered list. This is a feature: if you add a step in the middle, the numbering still works.

Nested lists indent by 2 or 4 spaces. Most renderers accept either, but 2 spaces is the convention.

- Top level
  - Nested
  - Also nested
- Back to top

Links

Inline links use [text](url):

[Uttir](https://uttir.com)

Renders as: Uttir

For tooltips, add a title in quotes after the URL:

[Uttir](https://uttir.com "Free online tools")

For email addresses, use a mailto link:

[Email support](mailto:[email protected])

Reference-style links (using a separate link definition) are useful when the same URL appears multiple times in a long document:

This is [a link][1] and [another link][1].

[1]: https://example.com "Optional title"

Images

Images use the same syntax as links, with a leading !:

![Alt text](image-url.png)
![Alt text](image-url.png "Optional title")

The alt text is the most important part. It is what screen readers announce, what shows up if the image fails to load, and what image search engines index. Always include meaningful alt text — not "image" or "" but a real description of what the image shows.

Code

Inline code uses single backticks. Code blocks use three backticks on a line by themselves above and below the code, optionally with a language identifier for syntax highlighting.

This is `inline code` in a sentence.

A fenced code block looks like this in the source — three
backticks on a line, your code, then three more backticks.
Optionally with a language identifier (javascript, python,
bash, etc.) right after the opening backticks.

Indenting with four spaces also creates a code block in older Markdown, but the fenced syntax (three backticks in a row) is the modern standard and supports syntax highlighting.

Common language identifiers: javascript, typescript, python, bash, json, html, css, markdown. Most renderers support many more.

Blockquotes

Blockquotes use >:

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

Renders as:

This is a blockquote. It can span multiple lines.

Nested blockquotes add another >:

> Outer
> > Inner

Horizontal rules

Three or more -, *, or _ on a line by themselves:

---

***

___

All three render as a horizontal rule (a thin line). Pick one and stick with it; mixing is allowed but messy.

Tables (GFM extension)

Tables are a GFM extension. The syntax:

| Column 1 | Column 2 | Column 3 |
| --- | --- | --- |
| Cell A | Cell B | Cell C |
| Cell D | Cell E | Cell F |

Renders as:

Column 1	Column 2	Column 3
Cell A	Cell B	Cell C
Cell D	Cell E	Cell F

You can align columns with colons in the separator row: :--- for left, :---: for center, ---: for right.

Task lists (GFM extension)

Task lists are checkboxes:

- [x] Done item
- [ ] Todo item
- [ ] Another todo

Renders as:

• Done item
• Todo item
• Another todo

GitHub uses this in issues and pull requests for tracking progress.

Escaping characters

Some characters have special meaning in Markdown and need to be escaped with a backslash if you want to use them literally:

• * renders as a literal asterisk
• _ renders as a literal underscore
• # renders as a literal hash
• ` renders as a literal backtick
• \ renders as a literal backslash

The most common case: writing about Markdown syntax in a Markdown document. Escape the special characters, or wrap them in inline code.

Line breaks and paragraphs

A blank line between text creates a new paragraph. A single line break within a paragraph does not create a new line in the rendered output — the renderer treats it as a space.

To force a line break, end a line with two spaces and a newline, or use a backslash at the end of a line. This is a GFM extension and is rendered differently by different renderers.

The reliable pattern: separate paragraphs with blank lines. Use lists or blockquotes for content that needs to stand out. Do not try to do line-break tricks.

HTML inside Markdown

Most renderers allow raw HTML inside Markdown. If you need something Markdown does not support (a table with merged cells, an iframe, custom styling), you can drop into HTML and back:

This is **Markdown**, and this is <strong>HTML</strong>.

<details>
<summary>Click to expand</summary>
Hidden content here.
</details>

This is most useful for documentation (where you occasionally need a feature the Markdown spec does not have) and less useful for casual writing (where the Markdown spec covers everything you need).

Common pitfalls

A few things that trip up new Markdown writers:

Forgetting the blank line between block elements

- List item 1
- List item 2
This text is a continuation of the list, not a new paragraph.

Add a blank line before the new paragraph to separate it from the list.

Using * for emphasis in the middle of a word

un*frigging*believable

This may or may not render as expected depending on the renderer. Some renderers do not handle mid-word emphasis. Use * to escape if you need a literal asterisk.

Trailing whitespace and line breaks

Many editors strip trailing whitespace on save, which can break the "two spaces at end of line" trick for line breaks. If you need precise line breaks, use HTML (<br>) or structure the content with lists.

Inconsistent list markers

Mixing - and * in the same list is valid but ugly. Pick one and use it throughout. - is the convention in most modern writing.

Markdown flavors

The original Markdown spec (Gruber, 2004) is small. The renderers you actually use have extended it. The two most common flavors:

• CommonMark — the standardized spec, with unambiguous rules. Most modern renderers are CommonMark-compliant.
• GitHub Flavored Markdown (GFM) — adds tables, task lists, strikethrough, autolinks. Used on GitHub and many other places.

Most tools document which flavor they support. The Uttir Markdown to HTML tool follows CommonMark plus the most common GFM extensions.

Where to use Markdown

The places that support Markdown or a close variant:

• GitHub, GitLab, Bitbucket — READMEs, issues, pull requests, comments
• Reddit, Discord, Slack — chat and posts
• Stack Overflow, Stack Exchange — questions and answers
• Notion, Obsidian, Logseq — personal knowledge bases
• Most static site generators (Hugo, Jekyll, Astro, SvelteKit, Next.js) — content
• Most modern CMSes (Ghost, Hashnode, DEV) — blog posts
• Documentation platforms (Read the Docs, Docusaurus, MkDocs) — docs

If you write for any of these, Markdown is the right tool.

Common questions

Is Markdown a replacement for HTML?

No. Markdown is a subset of HTML, designed to be readable as plain text and convertible to HTML. For anything Markdown does not support (tables with merged cells, custom styling, iframes, forms), drop into HTML. Most renderers allow it.

What is the difference between Markdown and a WYSIWYG editor?

A WYSIWYG editor (Word, Google Docs, Notion) shows you the rendered output and lets you click buttons to format. Markdown is plain text with a syntax for formatting. Markdown is faster to type, easier to version-control, and renders the same in any tool. WYSIWYG is more approachable for non-technical users.

Which Markdown flavor should I learn?

CommonMark + GFM. That covers 95% of what you will use. The other flavors (MultiMarkdown, Pandoc, Kramdown) add features you will rarely need.

How do I convert Markdown to HTML?

The Uttir Markdown to HTML tool does it in your browser, with no upload. For programmatic conversion, every programming language has a library: marked (JavaScript), markdown-it (JavaScript), Python-Markdown (Python), Redcarpet (Ruby), commonmark (Go, C, many others).

Bottom line

Markdown is the plain-text format for writing on the web. The basic syntax is small (headings, bold, italic, lists, links, code), the rest is optional. Bookmark this cheatsheet or paste your text into the Uttir Markdown to HTML tool for a quick rendered preview. That is the whole setup.