Cú pháp cơ bản Markdown: Hướng dẫn đầy đủ với ví dụ

Cú pháp cơ bản Markdown là nền tảng mà mọi lập trình viên, nhà văn và người sáng tạo nội dung cần nắm vững. Dù bạn đang viết tài liệu, soạn bài blog hay định dạng một issue trên GitHub, những yếu tố cốt lõi này là các khối xây dựng mà bạn sẽ sử dụng hàng ngày.

Hướng dẫn này sẽ đi qua từng yếu tố cú pháp cơ bản với các ví dụ rõ ràng, so sánh đầu ra HTML và những lỗi thường gặp cần tránh. Hãy đánh dấu trang này — bạn sẽ quay lại đây thường xuyên hơn bạn nghĩ.

Tiêu đề

Markdown Headings

Tiêu đề giúp cấu trúc nội dung của bạn thành một hệ thống phân cấp logic. Markdown hỗ trợ sáu cấp tiêu đề, được tạo bằng cách đặt ký hiệu # trước văn bản.

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

Đoạn mã trên tạo ra HTML sau:

<h1>Heading Level 1</h1>
<h2>Heading Level 2</h2>
<h3>Heading Level 3</h3>
<h4>Heading Level 4</h4>
<h5>Heading Level 5</h5>
<h6>Heading Level 6</h6>

Các phương pháp tốt nhất cho tiêu đề

Luôn thêm khoảng trắng giữa # và văn bản tiêu đề. Nếu không có khoảng trắng, một số trình phân tích sẽ không nhận diện đó là tiêu đề.

✅ ## This Works
❌ ##This Doesn't

Sử dụng tiêu đề theo thứ tự. Đừng nhảy từ H2 sang H4 — điều này phá vỡ cấu trúc logic của tài liệu và ảnh hưởng đến cả khả năng truy cập lẫn SEO. Hãy coi tiêu đề như một mục lục: mỗi cấp nên lồng nhau một cách logic dưới cấp phía trên.

Chỉ sử dụng một H1 trên mỗi trang. H1 là tiêu đề trang của bạn. Mọi thứ khác nên là H2 trở xuống.

Đoạn văn và Ngắt dòng

Đoạn văn là yếu tố Markdown đơn giản nhất — chỉ cần viết văn bản. Tách các đoạn văn bằng một dòng trống.

This is the first paragraph.

This is the second paragraph.

Ngắt dòng

Đây là nơi nhiều người mới bắt đầu hay bị nhầm lẫn. Nhấn Enter một lần không tạo ra dòng mới trong hầu hết các trình hiển thị Markdown. Bạn cần phải:

Kết thúc dòng bằng hai hoặc nhiều khoảng trắng (sau đó nhấn Enter)
Sử dụng thẻ HTML

This is the first line.
This is the second line.

Or use HTML:<br>
This starts a new line.

Lỗi thường gặp

Chỉ nhấn Enter giữa hai dòng sẽ gộp chúng thành một đoạn văn trong kết quả hiển thị:

Line one
Line two

Kết quả hiển thị sẽ là: "Line one Line two" — một dòng duy nhất. Luôn sử dụng dòng trống cho đoạn văn mới hoặc khoảng trắng ở cuối dòng để ngắt dòng trong cùng một đoạn văn.

Định dạng văn bản

Markdown Text Formatting

Markdown giúp việc nhấn mạnh văn bản trở nên dễ dàng. Dưới đây là các tùy chọn định dạng cốt lõi:

In đậm

Bao văn bản bằng hai dấu hoa thị hoặc hai dấu gạch dưới:

**This is bold text**
__This is also bold__

Đầu ra HTML: This is bold text

In nghiêng

Bao văn bản bằng một dấu hoa thị hoặc một dấu gạch dưới:

*This is italic text*
_This is also italic_

Đầu ra HTML: This is italic text

In đậm và nghiêng

Kết hợp ba dấu hoa thị cho cả hai:

***Bold and italic***
___Also bold and italic___
**_Or mix like this_**

Đầu ra HTML: Bold and italic

Gạch ngang

Sử dụng hai dấu ngã (đây là phần mở rộng GFM, nhưng được hỗ trợ gần như ở mọi nơi):

~~This text is crossed out~~

Đầu ra HTML: <del>This text is crossed out</del>

Lỗi thường gặp

Sử dụng dấu gạch dưới ở giữa một từ không hoạt động đáng tin cậy. Hãy dùng dấu hoa thị để nhấn mạnh giữa từ:

✅ This is**very**important
❌ This is__very__important

Trích dẫn khối

Trích dẫn khối được tạo bằng ký tự >. Chúng thường được sử dụng để trích dẫn nguồn, làm nổi bật các ghi chú quan trọng hoặc nhấn mạnh thông tin chính.

> Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
> — John Gruber

Đầu ra HTML:

<blockquote>
  <p>Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
  — John Gruber</p>
</blockquote>

Trích dẫn khối nhiều đoạn

Thêm > vào dòng trống giữa các đoạn:

> First paragraph of the quote.
>
> Second paragraph of the quote.

Trích dẫn khối lồng nhau

Sử dụng >> để lồng nhau:

> This is the outer quote.
>
>> This is a nested quote inside it.

Trích dẫn khối kết hợp với các yếu tố khác

Bạn có thể kết hợp trích dẫn khối với các định dạng Markdown khác:

> ### A Heading Inside a Quote
>
> - List item one
> - List item two
>
> Text with **bold** and *italic* formatting.

Danh sách

Markdown Lists

Danh sách là một trong những yếu tố Markdown được sử dụng thường xuyên nhất. Bạn sẽ gặp ba loại: danh sách không thứ tự, danh sách có thứ tự và danh sách công việc.

Danh sách không thứ tự

Sử dụng -, * hoặc + làm ký hiệu đánh dấu. Chọn một và sử dụng nhất quán:

- First item
- Second item
- Third item

Đầu ra HTML:

<ul>
  <li>First item</li>
  <li>Second item</li>
  <li>Third item</li>
</ul>

Danh sách có thứ tự

Sử dụng số theo sau bởi dấu chấm. Số thực tế không quan trọng — Markdown tự động đánh số:

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

Thú vị là đoạn mã sau cũng cho kết quả tương tự:

1. First step
1. Second step
1. Third step

Cả hai đều hiển thị thành danh sách được đánh số đúng 1-2-3. Tuy nhiên, phương pháp tốt nhất là sử dụng số tuần tự để dễ đọc trong tệp nguồn.

Danh sách lồng nhau

Thụt lề bằng hai hoặc bốn khoảng trắng để tạo danh sách con:

1. Main item
   - Sub-item A
   - Sub-item B
     - Sub-sub-item
2. Another main item

Danh sách công việc

Danh sách công việc (tính năng GFM) sử dụng - [ ] cho mục chưa hoàn thành và - [x] cho mục đã hoàn thành:

- [x] Write the draft
- [x] Add code examples
- [ ] Proofread the article
- [ ] Publish

Lỗi thường gặp

Quên dòng trống trước danh sách khi nó đứng sau một đoạn văn. Một số trình phân tích yêu cầu điều này:

✅ Here is my list:

- Item one
- Item two

❌ Here is my list:
- Item one
- Item two

Mã nguồn

Markdown Code

Hiển thị mã nguồn là một trong những tính năng mạnh nhất của Markdown, và việc làm đúng rất quan trọng cho khả năng đọc.

Mã nội tuyến

Bao mã trong dấu backtick đơn để hiển thị nội tuyến:

Use the `print()` function to output text.

Đầu ra HTML: Use the <code>print()</code> function to output text.

Nếu mã của bạn chứa dấu backtick, hãy sử dụng backtick kép:

``There is a literal `backtick` here.``

Khối mã

Đối với mã nhiều dòng, sử dụng ba dấu backtick (khối mã có rào) với mã định danh ngôn ngữ tùy chọn để tô sáng cú pháp:

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

Mã định danh ngôn ngữ (javascript, python, html, css, bash, v.v.) cho phép tô sáng cú pháp trong hầu hết các trình hiển thị. Luôn bao gồm nó — nó cải thiện đáng kể khả năng đọc.

Khối mã thụt lề

Bạn cũng có thể tạo khối mã bằng cách thụt lề mỗi dòng bốn khoảng trắng hoặc một tab:

    function add(a, b) {
      return a + b;
    }

Tuy nhiên, khối mã có rào được ưu tiên hơn vì chúng hỗ trợ tô sáng cú pháp và không yêu cầu thụt lề mỗi dòng.

Liên kết

Liên kết rất cần thiết để kết nối nội dung. Markdown hỗ trợ nhiều định dạng liên kết.

Liên kết nội tuyến

Định dạng phổ biến nhất — văn bản trong ngoặc vuông, URL trong ngoặc đơn:

[Visit Example](https://example.com)

Đầu ra HTML: <a href="https://example.com">Visit Example</a>

Liên kết có tiêu đề

Thêm tiêu đề trong dấu ngoặc kép sau URL (xuất hiện dưới dạng tooltip khi di chuột):

[Visit Example](https://example.com "Example Website")

Liên kết kiểu tham chiếu

Để văn bản nguồn sạch hơn khi có nhiều liên kết, sử dụng kiểu tham chiếu:

I use [Google][1] and [GitHub][2] daily.

[1]: https://google.com "Google"
[2]: https://github.com "GitHub"

Cách này giữ cho đoạn văn của bạn gọn gàng và nhóm tất cả URL ở cuối — đặc biệt hữu ích trong các tài liệu dài.

Liên kết tự động

Bao URL hoặc email trong dấu ngoặc nhọn để tạo liên kết tự động:

<https://example.com>
<contact@example.com>

Hầu hết các trình hiển thị hiện đại (như GitHub) cũng tự động tạo liên kết cho URL thô mà không cần dấu ngoặc nhọn, nhưng sử dụng chúng đảm bảo tính tương thích.

Lỗi thường gặp

Quên rằng khoảng trắng trong URL cần được mã hóa. Sử dụng %20 cho khoảng trắng:

✅ [My Doc](files/my%20document.pdf)
❌ [My Doc](files/my document.pdf)

Hình ảnh

Markdown Links and Images

Hình ảnh sử dụng cú pháp giống như liên kết, nhưng có thêm dấu chấm than ! ở phía trước:

![Alt text describing the image](/path/to/image.webp)

Đầu ra HTML: <img src="/path/to/image.webp" alt="Alt text describing the image">

Hình ảnh có tiêu đề

![A sunset over the ocean](/images/sunset.webp "Beautiful sunset")

Hình ảnh có liên kết

Kết hợp cú pháp liên kết và hình ảnh để tạo hình ảnh có thể nhấp:

[![Alt text](/images/photo.webp)](https://example.com)

Các phương pháp tốt nhất cho văn bản thay thế

Luôn viết văn bản thay thế mô tả. Nó phục vụ hai mục đích quan trọng:

Khả năng truy cập — trình đọc màn hình sử dụng nó để mô tả hình ảnh cho người khiếm thị
SEO — công cụ tìm kiếm sử dụng nó để hiểu nội dung hình ảnh

✅ ![Markdown syntax cheat sheet showing headings, lists, and links](/images/cheatsheet.webp)
❌ ![image](/images/cheatsheet.webp)
❌ ![](/images/cheatsheet.webp)

Đường kẻ ngang

Tạo đường kẻ ngang (ngắt chủ đề) để phân tách trực quan các phần. Sử dụng ba hoặc nhiều dấu gạch ngang, dấu hoa thị hoặc dấu gạch dưới:

---
***
___

Cả ba đều tạo ra cùng một HTML: <hr>

Phương pháp tốt nhất: Sử dụng --- nhất quán và luôn thêm dòng trống trước và sau:

Content above the rule.

---

Content below the rule.

Ký tự thoát

Nếu bạn muốn hiển thị dấu hoa thị hoặc ký hiệu thăng nguyên bản mà không kích hoạt định dạng Markdown thì sao? Sử dụng dấu gạch chéo ngược \ trước ký tự:

\* This is not italic \*
\# This is not a heading
\- This is not a list item

Đây là danh sách đầy đủ các ký tự bạn có thể thoát:

\   Backslash
`   Backtick
*   Asterisk
_   Underscore
{}  Curly braces
[]  Square brackets
()  Parentheses
#   Hash
+   Plus sign
-   Hyphen
.   Dot
!   Exclamation mark
|   Pipe

Bảng tra cứu nhanh

Đây là mọi yếu tố cú pháp cơ bản trong một bảng để tra cứu nhanh:

Element         Syntax              HTML
--------------  ------------------  -----------
Heading 1       # Text              <h1>
Heading 2       ## Text             <h2>
Heading 3       ### Text            <h3>
Bold            **text**            <strong>
Italic          *text*              <em>
Bold + Italic   ***text***          <strong><em>
Strikethrough   ~~text~~            <del>
Blockquote      > text              <blockquote>
Ordered list    1. item             <ol><li>
Unordered list  - item              <ul><li>
Inline code     `code`              <code>
Link            [text](url)         <a href>
Image           ![alt](src)         <img>
Horizontal rule ---                 <hr>
Line break      spaces + Enter      <br>

Hãy thực hành ngay

Bây giờ bạn đã học mọi yếu tố cú pháp cơ bản của Markdown, đã đến lúc sử dụng chúng. Đây là những gì cần làm tiếp theo:

Thực hành viết: Tạo một tệp notes.md và thử từng yếu tố cú pháp. Bạn viết càng nhiều, nó càng trở nên tự nhiên.
Sử dụng công cụ xem trước: Tính năng xem trước Markdown tích hợp của VS Code (Ctrl+Shift+V / Cmd+Shift+V) cho phép bạn xem kết quả hiển thị theo thời gian thực khi bạn gõ.
Chuyển đổi và chia sẻ: Khi tài liệu Markdown của bạn đã sẵn sàng, hãy biến đổi nó thành kết quả hoàn chỉnh — chuyển đổi Markdown sang HTML cho xuất bản web, tạo PDF cho tài liệu sẵn sàng in, hoặc xuất sang Word cho chỉnh sửa cộng tác.
Khám phá thêm: Khi bạn đã quen với cú pháp cơ bản, hãy tìm hiểu hướng dẫn cú pháp mở rộng Markdown cho bảng, chú thích cuối trang, danh sách định nghĩa và nhiều hơn nữa. Mới làm quen với Markdown? Hãy bắt đầu với Markdown là gì để có cái nhìn tổng quan.

Vẻ đẹp của Markdown là những yếu tố cơ bản này đã bao phủ phần lớn mọi thứ bạn cần viết. Nắm vững chúng một lần, và bạn sẽ sử dụng chúng ở mọi nơi — từ GitHub đến Notion, từ tài liệu đến các bài blog như bài này.