Markdown là gì? Cú pháp Markdown đầy đủ cho người mới

Markdown là ngôn ngữ đánh dấu nhẹ: bạn gõ văn bản thường kèm vài ký hiệu như #, **, - để tạo tiêu đề, chữ đậm, danh sách, rồi phần mềm tự chuyển thành HTML. File Markdown thường có đuôi .md, mở được bằng mọi trình soạn thảo văn bản, không cần phần mềm riêng.

Tóm tắt nhanh

• Markdown do John Gruber tạo năm 2004, nay phổ biến ở GitHub, tài liệu kỹ thuật, blog và nhiều CMS.
• Cú pháp cốt lõi chỉ gồm vài ký hiệu: # tiêu đề, ** đậm, * nghiêng, - danh sách, []() liên kết, ![]() ảnh.
• Bảng, gạch ngang chữ và tự nhận liên kết là phần mở rộng của GitHub Flavored Markdown (GFM), không thuộc CommonMark lõi.
• Markdown không có SEO riêng: công cụ tìm kiếm đọc HTML sinh ra, nên cấu trúc heading, liên kết và ảnh alt mới là thứ quan trọng.
• Trình soạn thảo Markdown của KDIGI CMS lưu nội dung dạng Markdown và trả HTML đã làm sạch qua API.

Markdown là gì và vì sao nhiều người dùng?

Markdown ra đời với mục tiêu rõ ràng: văn bản gốc phải đọc được ngay cả khi chưa chuyển đổi. Theo trang giới thiệu của Gruber, ý tưởng là viết dạng văn bản thuần dễ đọc, dễ viết, rồi chuyển sang HTML hợp lệ. Bạn có thể xem bản gốc tại Daring Fireball.

Bốn lý do khiến Markdown được dùng rộng rãi:

1. Học nhanh. Nắm khoảng mười ký hiệu là đủ viết bài hoàn chỉnh.
2. Không phụ thuộc phần mềm. File chỉ là văn bản, mở bằng Notepad, VS Code hay bất kỳ editor nào.
3. Dễ quản lý phiên bản. Văn bản thuần so sánh khác biệt bằng Git rất rõ.
4. Chuyển đổi linh hoạt. Cùng một nguồn Markdown có thể ra HTML, PDF hoặc trang web.

Điểm yếu cũng cần nói thẳng: Markdown chỉ có sẵn các định dạng cơ bản. Muốn căn giữa, đổi màu chữ hay bố cục nhiều cột, bạn phải chèn HTML hoặc dùng công cụ bổ sung.

Markdown, CommonMark và GFM khác nhau thế nào?

Bản mô tả gốc của Gruber có nhiều chỗ mơ hồ nên mỗi phần mềm hiểu một khác. CommonMark là bản đặc tả chuẩn hóa để mọi bộ xử lý cho kết quả giống nhau (spec.commonmark.org). GitHub Flavored Markdown (GFM) là tập mở rộng dựa trên CommonMark, thêm bảng, gạch ngang chữ, danh sách việc cần làm và tự nhận liên kết (github.github.com/gfm).

Khi gặp cú pháp "không chạy", hãy kiểm tra công cụ của bạn hỗ trợ biến thể nào. Bảng là ví dụ điển hình: có nơi hiểu, có nơi hiển thị nguyên ký tự |.

Bảng tra nhanh cú pháp Markdown

Kết quả	Cú pháp bạn gõ	Ghi chú
Tiêu đề cấp 1	# Tiêu đề	Từ # đến ###### cho cấp 1 đến 6, cần dấu cách sau #
Chữ đậm	**đậm**	Cũng dùng được __đậm__
Chữ nghiêng	*nghiêng*	Cũng dùng được _nghiêng_
Đậm và nghiêng	***cả hai***	Ba dấu sao quanh chữ
Gạch ngang chữ	~~xóa~~	Mở rộng GFM
Danh sách gạch đầu dòng	- mục	Cũng dùng được * hoặc +
Danh sách số	1. mục	Số thứ tự do trình hiển thị tự đánh
Liên kết	[chữ hiển thị](https://example.com)	Thêm tiêu đề: (url "tiêu đề")
Ảnh		Giống liên kết, thêm ! phía trước
Trích dẫn	> câu trích	Lồng được nhiều cấp bằng >>
Mã dòng	`code`	Bao bằng dấu huyền (backtick)
Khối mã	```bash rồi ```	Ghi tên ngôn ngữ ngay sau ba backtick
Đường kẻ ngang	---	Đứng riêng một dòng, có dòng trống phía trên
Xuống dòng cứng	Hai dấu cách hoặc \ cuối dòng	Một lần xuống dòng đơn thường không tạo <br>
Thoát ký tự	\*	Hiện nguyên dấu * thay vì định dạng

Các mục từ "Tiêu đề" đến "Thoát ký tự" đều là cú pháp CommonMark, trừ gạch ngang chữ (GFM).

Cú pháp cơ bản, có ví dụ

Tiêu đề và đoạn văn

## Tiêu đề cấp 2
### Tiêu đề cấp 3

Đây là một đoạn văn. Các đoạn cách nhau bằng một dòng trống.

Mẹo thực tế: trên một trang web chỉ nên có một H1. Trong bài blog, tiêu đề bài thường đã là H1 nên phần thân bắt đầu từ ##, và đi lần lượt ## rồi ###, không nhảy cấp.

Nhấn mạnh và danh sách

Từ này **rất quan trọng**, từ kia chỉ *hơi nghiêng*.

- Mục thứ nhất
- Mục thứ hai
  - Mục con (thụt vào hai hoặc bốn dấu cách)

1. Bước một
2. Bước hai

Lỗi hay gặp nhất là quên dòng trống trước danh sách hoặc thụt lề sai nên danh sách con biến thành chữ thường.

Liên kết và ảnh

Xem [tài liệu CommonMark](https://spec.commonmark.org/).

![Giao diện trình soạn thảo](editor.png)

Phần trong ngoặc vuông của ảnh là văn bản thay thế (alt). Hãy viết mô tả có nghĩa, vì đó là thứ trình đọc màn hình và công cụ tìm kiếm đọc được.

Khối mã

Bao đoạn mã bằng ba dấu backtick, có thể ghi tên ngôn ngữ để tô màu:

```bash
docker compose up -d
```

Đoạn mã nằm trong khối sẽ không bị diễn giải, nên bạn gõ * hay # thoải mái bên trong.

Bảng trong Markdown (GFM)

Bảng dùng ký tự | để chia cột và hàng thứ hai gồm dấu gạch để phân tách tiêu đề:

| Cột A | Cột B | Cột C |
| :--- | :---: | ---: |
| trái | giữa | phải |
| 1 | 2 | 3 |

Dấu hai chấm trong hàng phân tách quyết định căn lề: :--- căn trái, :---: căn giữa, ---: căn phải. Bảng không bắt buộc các cột thẳng hàng trong file nguồn, nhưng căn thẳng sẽ dễ đọc hơn. Muốn hiện ký tự | trong ô, viết \|. Ô bảng chỉ chứa nội dung một dòng; nếu cần xuống dòng trong ô, nhiều công cụ chấp nhận thẻ <br>.

Từ Markdown sang HTML: chuyện gì xảy ra phía sau?

Một bộ chuyển đổi (parser) đọc từng dòng Markdown và sinh HTML tương ứng:

Markdown	HTML sinh ra
## Giới thiệu	<h2>Giới thiệu</h2>
**đậm**	<strong>đậm</strong>
[KDIGI](https://kdigi.vn)	<a href="https://kdigi.vn">KDIGI</a>
- a rồi - b	<ul><li>a</li><li>b</li></ul>

Điều này giải thích câu hỏi về SEO. Markdown không phải yếu tố xếp hạng. Googlebot nhận HTML cuối cùng, nên điều quan trọng là HTML đó có một H1, heading phân cấp, ảnh có alt, liên kết nội bộ rõ ràng và dữ liệu có cấu trúc. Phần dữ liệu có cấu trúc thuộc về CMS; tham khảo SEO và JSON-LD trong KDIGI CMS.

Về bảo mật, bộ chuyển đổi cho phép chèn HTML thô trong Markdown. Nếu nội dung đến từ người dùng bên ngoài, HTML sinh ra phải được làm sạch (sanitize) trước khi hiển thị, nếu không có nguy cơ chèn script.

File .md mở bằng gì?

• Soạn thảo: mọi editor văn bản. VS Code có xem trước Markdown tích hợp (mở bằng lệnh Markdown: Open Preview).
• Xem đã hiển thị: GitHub tự hiển thị file .md trong repository, trình duyệt thì cần tiện ích hoặc công cụ chuyển đổi.
• Đuôi file: phổ biến là .md; .markdown cũng được dùng. Kiểu MIME chính thức text/markdown được đăng ký trong RFC 7763.

Soạn Markdown trong KDIGI CMS

Với người làm nội dung, gõ ký hiệu bằng tay không phải lúc nào cũng tiện. Trình soạn thảo Markdown của KDIGI CMS dùng thư viện Milkdown, vừa lưu Markdown thuần vừa có giao diện trực quan. Theo tài liệu dự án, các tính năng chính gồm:

• Slash menu: gõ / để mở menu lệnh gồm tiêu đề 1-6, danh sách, danh sách việc cần làm, khối mã, trích dẫn, đường kẻ, liên kết, bảng và ảnh.
• Chọn liên kết nội bộ: gõ @ rồi tên bài để tìm trang, bài viết, sản phẩm của cùng website và chèn liên kết [Tiêu đề](/đường-dẫn).
• Dán nội dung giàu định dạng: nội dung từ Google Docs hay Word được chuyển sang GFM; ảnh dán hoặc kéo thả được tải lên thư viện media.
• Tìm và thay thế, thanh outline và bảng phím tắt (Ctrl/Cmd+/) liệt kê mọi phím tắt và quy tắc gõ Markdown.
• Shortcode: chèn đoạn nội dung dùng lại bằng [sc name="..."/].

Phía API, trường contentMd là nguồn Markdown gốc; qua REST, hệ thống trả HTML đã làm sạch ở trường content. Bộ chuyển đổi dùng markdown-it rồi lọc bằng sanitize-html theo danh sách thẻ cho phép, nên <script>, <iframe> và thuộc tính sự kiện không lọt ra ngoài. Frontend của bạn nhận HTML sẵn để hiển thị, đúng tinh thần Headless CMS và API.

Lưu ý theo cấu hình hiện tại của KDIGI CMS: breaks đang tắt, nghĩa là một lần xuống dòng đơn trong đoạn không thành thẻ <br>; muốn xuống dòng cứng, dùng hai dấu cách hoặc dấu \ cuối dòng như bảng tra ở trên.

Mẹo viết Markdown sạch cho bài SEO

1. Heading có thứ bậc: ## cho ý lớn, ### cho ý con, không dùng heading chỉ để làm chữ to.
2. Đoạn mở đầu trả lời ngay câu hỏi của bài trong vài câu đầu.
3. Ảnh luôn có alt mô tả đúng nội dung.
4. Liên kết nội bộ có anchor mô tả, tránh "bấm vào đây".
5. Dùng bảng khi so sánh nhiều tiêu chí, dùng danh sách khi liệt kê bước.
6. Khối mã có tên ngôn ngữ để dễ đọc và dễ sao chép.

Câu hỏi thường gặp

Markdown là gì?

Markdown là ngôn ngữ đánh dấu nhẹ cho phép viết văn bản có định dạng bằng ký hiệu đơn giản như #, **, -, rồi chuyển thành HTML. Nó dễ học, file chỉ là văn bản thuần với đuôi .md, và được dùng nhiều trong tài liệu kỹ thuật, GitHub, blog và CMS.

File .md mở bằng gì?

Bạn mở file .md bằng bất kỳ trình soạn thảo văn bản nào như Notepad hoặc VS Code. Muốn xem bản đã hiển thị định dạng, dùng tính năng xem trước Markdown của VS Code, xem trên GitHub, hoặc một công cụ chuyển Markdown sang HTML.

Markdown có dùng cho SEO được không?

Được, nhưng Markdown không tự cải thiện thứ hạng. Công cụ tìm kiếm đọc HTML sinh ra từ Markdown, nên hiệu quả SEO đến từ heading đúng cấp, ảnh có alt, liên kết nội bộ và dữ liệu có cấu trúc mà CMS hoặc frontend bổ sung.

Markdown khác HTML thế nào?

HTML mô tả cấu trúc trang bằng thẻ, rất mạnh nhưng dài dòng. Markdown là lớp viết tắt cho các cấu trúc phổ biến và được chuyển thành HTML. Khi Markdown thiếu tính năng, nhiều bộ xử lý cho phép chèn HTML thô, tùy cấu hình bảo mật.

CommonMark và GFM là gì?

CommonMark là đặc tả Markdown chuẩn hóa để các công cụ cho kết quả nhất quán. GFM là phần mở rộng của GitHub dựa trên CommonMark, thêm bảng, gạch ngang chữ, danh sách việc cần làm và tự nhận liên kết.

Bước tiếp theo

Nếu bạn đang chọn nền tảng để viết nội dung bằng Markdown, hãy xem cách Headless CMS tách nội dung khỏi giao diện, đọc chi tiết trình soạn thảo Markdown của KDIGI CMS, hoặc tự chạy thử bằng Docker theo bài Docker là gì và hướng dẫn tự host.

Nguồn

• John Gruber, Markdown: daringfireball.net/projects/markdown
• CommonMark Spec: spec.commonmark.org
• GitHub Flavored Markdown Spec: github.github.com/gfm
• RFC 7763, The text/markdown Media Type: rfc-editor.org/rfc/rfc7763
• Tài liệu KDIGI CMS, Markdown editor và shortcodes (docs/content-markdown.md): github.com/kdigivn/kdigi-cms-open