Markdown Syntax Cheat Sheet: All Tags Guide

Introduction to Markdown

Markdown is a lightweight markup language that allows you to write using an easy-to-read, easy-to-write plain text format, which then converts to valid XHTML (or HTML). Created by John Gruber in 2004, it has become the de facto standard for developers, technical writers, and content creators.

It's used everywhere: GitHub READMEs, technical documentation, Slack messages, Notion pages, and static site generators like Jekyll and Hugo.

Basic Formatting

Headings

Headings are created by adding one or more # symbols before your heading text. The number of # you use will determine the size of the heading.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Best Practice: Always put a space between the # and the heading name.

Emphasis & Styling

You can add emphasis by bolding or italicizing text.

• Bold: Use double asterisks ** or underscores __
• Italic: Use single asterisks * or underscores _
• Bold and Italic: Use triple asterisks ***
• Strikethrough: Use double tildes ~~

**This is bold text**
*This is italic text*
***This is bold and italic***
~~This text is crossed out~~

Paragraphs & Line Breaks

To create a paragraph, simply leave a blank line between lines of text.

To create a line break (without a new paragraph), end a line with two or more spaces and then hit return.

Structured Content

Lists

Unordered Lists Use hyphens -, asterisks *, or plus signs + followed by a space.

- Item 1
- Item 2
  - Nested Item 2a
  - Nested Item 2b

Ordered Lists Use numbers followed by a period 1.. The numbers don't even have to be in order!

1. First item
2. Second item
3. Third item

Task Lists Perfect for tracking to-do items in GitHub issues.

- [x] Completed task
- [ ] Incomplete task

Blockquotes

Blockquotes are used to draw attention to a quote or specific information. Use the > symbol.

> This is a blockquote.
>
> > This is a nested blockquote.

Links and Media

Links

To create a link, enclose the link text in brackets [] and then follow it immediately with the URL in parenthesis ().

[JSON View](https://jsonview.help)
[Link with Title](https://example.com "Hover Title")

Images

Images are similar to links, but with an exclamation mark ! in front.

![Alt Text for Accessibility](/path/to/image.jpg)
![Logo](https://example.com/logo.png "Optional Title")

Tip: Always provide descriptive alt text for accessibility and SEO.

Code and Syntax Highlighting

Inline Code

Use single backticks ``` to denote code within a sentence.

Use the `console.log()` function to print to the console.

Code Blocks

Use triple backticks ``````` to create a multi-line code block. You can specify a language for syntax highlighting.

```javascript
function greet(name) {
  console.log('Hello, ' + name);
}

Supported languages include `javascript`, `python`, `html`, `css`, `java`, `cpp`, `sql`, `bash`, `json`, and many more.

## Tables

Tables are not part of the original Markdown spec but are supported in GitHub Flavored Markdown (GFM). Use whitespace to align columns for readability in the raw file (optional but recommended).

```markdown
| Header 1 | Header 2 | Header 3 |
| :------- | :------: | -------: |
| Left     | Center   | Right    |
| Text     | Text     | Text     |

• :--- Left align
• :---: Center align
• ---: Right align

Advanced Features

Horizontal Rules

Create a thematic break or horizontal line using three or more asterisks ***, dashes ---, or underscores ___ on a line by themselves.

---

Escaping Characters

If you need to display a literal character that would otherwise be used for formatting (like a * or #), adhere a backslash \ before it.

\* This is not a list item, it's a literal asterisk.

HTML in Markdown

For complex formatting that Markdown doesn't support (like colored text or centering), you can use raw HTML tags.

<p align="center">Centered Text</p>
<details>
  <summary>Click to expand</summary>
  Hidden content here!
</details>

GitHub Flavored Markdown (GFM)

GitHub introduced several extensions that are now widely supported:

1. Auto-linking URLs: Just paste a URL, and it becomes a link.
2. Mentions: @username links to a user profile.
3. Issue References: #123 links to issue/PR number 123.
4. Emoji Support: :smile: renders as 😄.
5. Footnotes: [^1] adds a footnote reference.

Best Practices

1. Use Blank Lines: Generously use blank lines to separate headings, lists, and paragraphs. It improves readability.
2. Accessible Headers: Do not skip heading levels (e.g., don't jump from H1 to H3).
3. Descriptive Links: Avoid "click here". Use descriptive text like "Read the documentation".
4. Consistent Style: Stick to one style for lists (e.g., always use - or always use *).
5. Preview Often: Use a tool like our Markdown Editor to see how your content renders in real-time.

Conclusion

Markdown is one of the most valuable skills for any technical professional. It's portable, readable even in raw form, and universally supported. Whether you're writing a quick gist or a full-length technical book, Markdown is the right tool for the job.

Bookmark this cheat sheet and start writing!