Markdown Basic Syntax Guide

What is Markdown?

Markdown is a lightweight markup language that lets you write formatted documents using simple plain text syntax. It was created by John Gruber in 2004 with the goal of making documents easy to read even in their raw source form.

Why Use Markdown?

Simple and Easy to Learn: Intuitive syntax that can be picked up in minutes
Widely Supported: Tools like GitHub, GitLab, Notion, HackMD, and VS Code all support it
Focus on Content: No need to click formatting buttons, keep your hands on the keyboard
Version Control Friendly: Plain text format, perfect for use with Git
Multi-Format Output: Easily convert to HTML, PDF, slides, and more

Common Uses for Markdown

Writing technical documentation and READMEs
Blog posts
Notes and knowledge management
GitHub Issues and Pull Request descriptions
Email and message formatting

Headings

Use the # symbol to create headings. The number of # symbols determines the heading level (1-6):

# H1 Heading
## H2 Heading
### H3 Heading
#### H4 Heading
##### H5 Heading
###### H6 Heading
Loading...

Tip: There must be a space between # and the heading text. It is generally recommended to use only one H1 heading per document and use H2 and below for the rest.

Paragraphs & Line Breaks

Paragraphs are separated by a blank line:

This is the first paragraph.

This is the second paragraph.
Loading...

If you only need a line break without starting a new paragraph, add two spaces at the end of the line before pressing Enter, or use the <br> tag:

First line
Second line (the previous line ends with two spaces)

First line<br>
Second line (using the HTML br tag)
Loading...

Text Emphasis

Bold

**This is bold text**
__This is also bold text__
Loading...

This is bold text

Italic

*This is italic text*
_This is also italic text_
Loading...

This is italic text

Bold & Italic

***This is bold and italic***
___This is also bold and italic___
Loading...

This is bold and italic

Strikethrough

~~This is deleted text~~
Loading...

~~This is deleted text~~

Highlight

Some platforms support using == to highlight text:

==This is highlighted text==
Loading...

Lists

Unordered List

Use -, *, or + to create unordered lists:

- Item 1
  - Sub-item 1.1
  - Sub-item 1.2
- Item 2
  - Sub-item 2.1
    - Sub-sub-item 2.1.1
Loading...

Item 1
- Sub-item 1.1
- Sub-item 1.2
Item 2
- Sub-item 2.1
  - Sub-sub-item 2.1.1

Ordered List

Use numbers followed by . to create ordered lists:

1. First item
2. Second item
   1. Sub-item of second 1
   2. Sub-item of second 2
3. Third item
Loading...

First item
Second item
1. Sub-item of second 1
2. Sub-item of second 2
Third item

Tip: The numbers in ordered lists do not need to be sequential as Markdown will auto-number them. However, it is recommended to write them in order for better source readability.

Blockquote

Use > to create blockquotes:

> This is a blockquote.

> This is a multi-line blockquote
> that spans multiple lines.

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

This is a blockquote.

This is a nested blockquote.

Blockquotes can also contain other Markdown elements:

Note: You can use bold, italic, code, and other formatting inside blockquotes.

Lists work too

Very useful

Code

Inline Code

Wrap code with backticks `:

Use `console.log()` to print messages.
Loading...

Use console.log() to print messages.

Code Blocks

Use triple backticks ``` with a language identifier to create code blocks:

```javascript
function greet(name) {
  console.log(`Hello, ${name}!`)
}
```
Loading...

function greet(name) {
  console.log(`Hello, ${name}!`)
}
Loading...

Common language identifiers: javascript, python, bash, html, css, json, yaml, sql, go, rust, etc.

Diff

Use the diff language identifier to display code changes:

```diff
- const old = 'removed'
+ const new = 'added'
```
Loading...

- const old = 'removed'
+ const new = 'added'
Loading...

Links

Inline Link

[Link text](https://www.example.com)
[Link with title](https://www.example.com "Text shown on hover")
Loading...

Link text

Reference Link

Useful when the same link is used multiple times in a document:

This text contains a [reference link][1] and [another link][example].

[1]: https://www.example.com
[example]: https://www.example.com/page
Loading...

Autolink

Paste URLs directly or use angle brackets:

<https://www.example.com>
<[email protected]>
Loading...

Images

![Alt text](https://picsum.photos/200/300)
![Image with title](https://picsum.photos/200/300 "Image title")
Loading...

Alt text

You can also use reference-style links:

![Alt text][image-id]

[image-id]: https://picsum.photos/200/300 "Image title"
Loading...

Tip: If you need to control image size, use the HTML <img> tag:
<img src="https://picsum.photos/200/300" width="200" alt="Image description">
Loading...

Tables

Use | and - to create tables:

| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |
Loading...

Header 1	Header 2	Header 3
Cell 1	Cell 2	Cell 3
Cell 4	Cell 5	Cell 6

Table Alignment

Use : to control alignment:

| Left Aligned | Center Aligned | Right Aligned |
| :----------- | :------------: | ------------: |
| Left         | Center         | Right         |
| Data         | Data           | Data          |
Loading...

Left Aligned	Center Aligned	Right Aligned
Left	Center	Right
Data	Data	Data

Task Lists

Use - [ ] and - [x] to create task lists:

- [x] Completed item
- [x] This one is done too
- [ ] Incomplete item
- [ ] To-do item
Loading...

Completed item
This one is done too
Incomplete item
To-do item

Horizontal Rule

Use three or more -, *, or _ to create a horizontal rule:

---
***
___
Loading...

Escaping Special Characters

To display Markdown special characters, use a backslash \ to escape them:

\* will not become italic \*
\# will not become a heading
\[ will not become a link \]
Loading...

Escapable characters: \, `, *, _, {}, [], (), #, +, -, ., !, |

Footnotes

Footnotes let you add supplementary information without disrupting the reading flow:

This is a paragraph with a footnote.[^1]

Another paragraph can also have a footnote.[^note]

[^1]: This is the first footnote content.
[^note]: Footnotes can also use text as identifiers.
Loading...

This is a paragraph with a footnote.¹

Collapsible Sections

Use the HTML <details> tag to create collapsible content blocks:

<details>
<summary>Click to expand</summary>

This is the collapsed content.

It can contain any Markdown syntax:
- Lists
- **Bold**
- `Code`

</details>
Loading...

<details> <summary>Click to expand</summary>

This is the collapsed content.

</details>

Math Equations

Some platforms (like GitHub and HackMD) support LaTeX math equations:

Inline Equations

Inline equation: $E = mc^2$
Loading...

Inline equation: $E = mc^2$

Block Equations

$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n
$$
Loading...

$$ \sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n $$

Custom HTML

You can embed HTML tags directly in Markdown for formatting effects that Markdown syntax cannot achieve:

<div style="text-align: center;">
  <h2>Centered Heading</h2>
  <p>This text is centered.</p>
</div>

<kbd>Ctrl</kbd> + <kbd>C</kbd>

<mark>Highlighted text</mark>

<sup>Superscript</sup> and <sub>Subscript</sub>
Loading...

GitHub Flavored Markdown

GitHub supports some additional Markdown syntax:

Alerts

> [!NOTE]
> This is a note.

> [!TIP]
> This is a useful tip.

> [!IMPORTANT]
> This is important information.

> [!WARNING]
> This is a warning.

> [!CAUTION]
> This is a danger warning.
Loading...

Emoji

:smile: :heart: :thumbsup: :rocket: :star:
Loading...

Mentions & References

@username          Mention a user
#123               Reference an Issue or PR
SHA-hash           Reference a specific commit
Loading...

Best Practices

Be Consistent: Once you pick a style (e.g., using - or * for list markers), stick with it throughout the document
Use Blank Lines: Add blank lines between paragraphs and around headings to make the source more readable
Structure with Headings: Use H2-H4 headings appropriately to give your document a clear hierarchy
Alt Text: Always add alt text to images for better accessibility
Preview: Use preview features to verify the formatting after writing
Use Code Blocks: Specify the language for syntax highlighting to improve readability

This is the footnote content. ↩