Mastering Markdown: A Complete Guide to Syntax and Best Practices

1. Basic Syntax

1.1 Headings

Markdown supports six heading levels (H1‑H6). Prefix the heading text with 1‑6 “#” symbols followed by a space.

# This is an H1 heading
## This is an H2 heading
### This is an H3 heading
#### This is an H4 heading
##### This is an H5 heading
###### This is an H6 heading

1.2 Paragraphs

Paragraphs are written as plain text separated by a blank line.

This is the first paragraph.

This is the second paragraph.

1.3 Line Breaks

Insert a line break inside a paragraph by ending the line with two spaces and a newline.

This is one line.␣␣
This is the next line after a break.

1.4 Emphasis

Italic: wrap text with a single * or _.

Bold: wrap text with double ** or __.

Bold + Italic: wrap text with triple *** or ___.

*italic text*
**bold text**
***bold italic text***

1.5 Lists

Unordered list: start each item with -, * or +.

Ordered list: start each item with a number followed by a period.

- Item 1
- Item 2
  - Sub‑item 2.1
  - Sub‑item 2.2
- Item 3

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

1.6 Links

Inline link: [link text](URL) Reference link: define a label, then use [link text][label].

[Baidu](https://www.baidu.com)

[Google]: https://www.google.com

1.7 Images

Image syntax mirrors links but starts with an exclamation mark.

![Alt text](https://example.com/image.jpg)

1.8 Code

Inline code: wrap with backticks `code`.

Fenced code block: surround with three backticks ```.

This is `code` inline.

```
This is a code block.
```

2. Advanced Usage

2.1 Tables

Basic tables use | to separate columns and a row of dashes to separate the header.

| Name | Age | Gender |
| ---- | --- | ------ |
| Xiao Ming | 25 | Male |
| Xiao Hong | 22 | Female |

2.2 Blockquotes

Prefix a line with > to create a blockquote.

> This is a quoted line.

2.3 Task Lists

Task lists use - [ ] for unchecked items and - [x] for checked items.

- [ ] Write documentation
- [x] Implement feature

2.4 Horizontal Rules

Three or more asterisks, hyphens, or underscores create a horizontal rule.

---

2.5 Embedded HTML

Raw HTML can be embedded for layouts not supported by Markdown.

<p>This is a paragraph with <strong>bold</strong> text.</p>

3. Common Application Scenarios

Technical documentation (e.g., README files on GitHub/GitLab).

Blog writing with static‑site generators such as Hexo and Jekyll.

Note‑taking and knowledge‑management tools like Obsidian, Notion, Typora.

Code comments and inline documentation that can be rendered to API docs.

4. Caveats

4.1 Rendering Differences

Different renderers (GitHub Flavored Markdown, CommonMark, Pandoc, etc.) may support slightly different subsets of the syntax. Consult the target platform’s documentation.

4.2 Layout Limitations

Markdown’s layout capabilities are simple; complex tables or page designs may require fallback to raw HTML.

4.3 Image and Link Paths

Ensure relative and absolute paths are correct for the hosting platform, especially on Git‑based services.

4.4 Extended Syntax

Some platforms offer extensions such as footnotes, math formulas, or Mermaid diagrams. Use them only when the target renderer supports them.