Markdown là gì? Cú pháp, CommonMark và GFM

Hãy nghĩ đến tệp README của một dự án phần mềm, những danh sách có tiêu đề trong ứng dụng ghi chú, hay những chữ bạn in đậm bằng dấu sao trong ứng dụng nhắn tin. Đằng sau tất cả là cùng một ý tưởng: Markdown. Markdown là một ngôn ngữ đánh dấu nhẹ, cho phép bạn định nghĩa tiêu đề, danh sách, liên kết và bảng bằng cách thêm vài ký hiệu đơn giản vào văn bản thuần. Tệp vẫn dễ đọc trong mọi trình soạn thảo văn bản, nhưng có thể biến thành một trang HTML gọn gàng, một tài liệu Word hay một tệp PDF bất cứ khi nào bạn cần. Bài viết này trình bày Markdown ra đời thế nào, cú pháp cốt lõi, sự khác biệt giữa CommonMark và GitHub Flavored Markdown, và những điều cần lưu ý khi chuyển đổi tệp MD.

Markdown là gì?

Markdown vừa là một bộ quy ước viết, vừa là tên gọi chung của các công cụ chuyển văn bản viết theo quy ước đó sang HTML. Tệp thường được lưu với phần mở rộng .md hoặc .markdown. Theo người tạo ra nó, John Gruber, mục tiêu thiết kế quan trọng nhất là dễ đọc: một tài liệu Markdown phải có thể xuất bản nguyên trạng dưới dạng văn bản thuần mà không trông như đã bị đánh dấu bằng thẻ hay lệnh định dạng. Chỗ HTML cần <strong>quan trọng</strong> thì Markdown dùng **quan trọng**, và ngay cả bản thô cũng đọc rất tự nhiên.

Sơ lược lịch sử

John Gruber tạo ra Markdown năm 2004, với Aaron Swartz đóng góp như người cùng thảo luận, góp ý cho các ý tưởng của ông. Cú pháp dựa trên những quy ước trong email văn bản thuần (dấu sao để nhấn mạnh, gạch ngang cho danh sách) và trên các ngôn ngữ đánh dấu trước đó như setext và Textile. Phiên bản 1.0.1 của Markdown.pl, script Perl mà Gruber công bố trên trang Daring Fireball của mình, có ngày 17 tháng 12 năm 2004.

Tuy nhiên, phần mô tả của Gruber là lời giải thích qua ví dụ chứ không phải một đặc tả chính thức. Những trường hợp mơ hồ (danh sách lồng nhau, khối mã thụt lề, trộn lẫn HTML) khiến mỗi bản triển khai tự đưa ra lựa chọn riêng, và cùng một đoạn văn bản bắt đầu cho ra kết quả khác nhau ở các công cụ khác nhau. Sau đó có hai phản hồi lớn:

• CommonMark (2014): một đặc tả do John MacFarlane dẫn dắt, định nghĩa Markdown một cách rõ ràng và có thể kiểm thử bằng hàng trăm ví dụ. Các phiên bản đầu tiên xuất hiện vào mùa thu năm 2014; phiên bản hiện tại là 0.31.2, ngày 28 tháng 1 năm 2024. Đặc tả này vẫn chưa được công bố bản 1.0.
• GitHub Flavored Markdown (GFM, 2017): đặc tả chính thức của GitHub xây dựng trên nền CommonMark. Nó bổ sung các phần mở rộng như bảng, danh sách công việc, gạch ngang chữ, tự động nhận liên kết mở rộng và, vì lý do bảo mật, lọc bỏ một số thẻ HTML thô. Đặc tả được công bố gần nhất là 0.29-gfm, ngày 6 tháng 4 năm 2019.

Markdown cũng được công nhận trong hạ tầng internet: RFC 7763, công bố tháng 3 năm 2016, đã đăng ký kiểu phương tiện (MIME type) text/markdown với tham số tùy chọn variant cho biết tác giả dùng biến thể Markdown nào.

Các biến thể Markdown chính

Ngoài CommonMark và GFM còn có những biến thể phổ biến khác. RFC 7764, công bố cùng RFC 7763, đã đăng ký một số biến thể và đưa ra hướng dẫn sử dụng:

• Markdown Extra: một phần mở rộng ra đời sớm, bổ sung chú thích cuối trang, danh sách định nghĩa và bảng.
• MultiMarkdown: biến thể hướng tới viết học thuật, có siêu dữ liệu, trích dẫn và tham chiếu chéo.
• Pandoc Markdown: biến thể mà trình chuyển đổi Pandoc sử dụng, với nhiều phần mở rộng để viết sách và bài báo.

Một quy tắc thực tế: nếu tài liệu của bạn chỉ dùng tiêu đề, danh sách, liên kết, mã và bảng đơn giản, nó sẽ hiển thị giống nhau ở hầu hết mọi nơi. Nếu bạn dựa vào chú thích cuối trang, danh sách định nghĩa hoặc các kiểu khối đặc biệt, hãy kiểm tra môi trường đích hỗ trợ biến thể nào.

Cú pháp cốt lõi

Phần Markdown bạn cần hằng ngày chỉ mất vài phút để học:

# Tiêu đề cấp một
## Tiêu đề cấp hai
Đoạn văn này có **đậm**, *nghiêng* và `code`.
- Danh sách gạch đầu dòng
- Mục thứ hai
  - Mục con thụt vào
1. Danh sách đánh số
2. Bước thứ hai
[Văn bản liên kết](https://example.com)
![Mô tả hình ảnh](image.png)
> Trích dẫn
```
Khối mã nhiều dòng
```

Bảng và danh sách công việc do GFM bổ sung trông như sau:

| Định dạng | Phần mở rộng |
|-----------|--------------|
| Markdown | .md |
| Văn bản thuần | .txt |
- [x] Viết bản nháp
- [ ] Rà soát lại

Các đoạn văn được ngăn cách bằng dòng trống. Một lần xuống dòng đơn lẻ được hầu hết các bản triển khai coi là vẫn thuộc cùng một đoạn; để buộc xuống dòng, hãy kết thúc dòng bằng hai khoảng trắng. Bạn cũng có thể viết HTML trực tiếp bên trong Markdown. CommonMark cho phép điều này, tuy các môi trường như GFM chặn một số thẻ vì lý do bảo mật.

Markdown được dùng ở đâu?

• Phát triển phần mềm: README, nhật ký thay đổi (changelog) và hướng dẫn đóng góp, cùng các issue và bình luận review mã trên những nền tảng như GitHub và GitLab.
• Tài liệu kỹ thuật: các trình tạo trang tĩnh xây dựng website từ tệp Markdown.
• Ghi chú: nhiều ứng dụng ghi chú lưu hoặc xuất ghi chú dưới dạng Markdown.
• Nền tảng trò chuyện và cộng đồng: các nền tảng như Reddit và Discord dùng các biến thể Markdown.
• Viết và xuất bản: tạo HTML, PDF, DOCX và EPUB từ một nguồn Markdown duy nhất bằng các công cụ như Pandoc.
• Công cụ AI: các trợ lý AI dạng trò chuyện thường định dạng câu trả lời bằng Markdown.

Ưu điểm và nhược điểm

Những chương trình nào mở được Markdown?

Vì Markdown là văn bản thuần, nó mở được trong mọi trình soạn thảo văn bản, kể cả Notepad và TextEdit. Để xem bản đã định dạng, bạn có thể dùng chế độ xem trước Markdown có sẵn trong Visual Studio Code hoặc các trình soạn thảo chuyên dụng như Obsidian và Typora. GitHub và GitLab tự động hiển thị các tệp .md trong kho mã. Ngược lại, Word không mở Markdown dưới dạng văn bản có định dạng, nên bạn cần chuyển đổi tệp trước.

Các lỗi thường gặp và cách khắc phục

Danh sách hoặc tiêu đề không hiển thị đúng

CommonMark yêu cầu một khoảng trắng sau ký hiệu tiêu đề: ## Tiêu đề, không phải ##Tiêu đề. Một danh sách đứng sau đoạn văn cũng thường cần một dòng trống ở giữa để hiển thị đúng.

Các dòng bị dính vào nhau

Một lần xuống dòng đơn lẻ không tách đoạn. Hãy để một dòng trống để bắt đầu đoạn mới, hoặc kết thúc dòng bằng hai khoảng trắng để xuống dòng trong cùng một đoạn.

Bảng hiển thị trên nền tảng này nhưng không hiển thị trên nền tảng khác

Bảng không thuộc Markdown gốc của Gruber hay phần lõi của CommonMark; chúng đến từ các phần mở rộng như GFM. Hãy kiểm tra nền tảng đích hỗ trợ biến thể nào.

Đoạn văn bắt đầu bằng số bị biến thành danh sách đánh số

Một dòng như "2024. là một năm bận rộn" bắt đầu bằng chữ số và dấu chấm, nên có thể bị hiểu là danh sách. Hãy thoát dấu chấm bằng dấu gạch chéo ngược (2024\.) để tránh điều này.

Mẹo khi chuyển đổi tệp Markdown

Trên trình chuyển đổi của chúng tôi, tệp Markdown được tải lên máy chủ và bị xóa trong vòng 30 phút. Để đọc tệp, chúng tôi dùng thư viện Markdig với CommonMark và các phần mở rộng kiểu GitHub (bảng, danh sách công việc, chú thích cuối trang, tự động nhận liên kết).

• Markdown sang PDF và Markdown sang Word giữ tiêu đề, danh sách, khối mã, trích dẫn và bảng có viền. Các ô đánh dấu của danh sách công việc được chuyển thành ký tự ☑ và ☐ để vẫn nhìn thấy được trong Word và PDF. Văn bản mặc định dùng phông có chân cỡ 12 pt, còn khối mã dùng phông đơn cách (monospace).
• Markdown sang HTML biến một tệp README thành trang web độc lập có khai báo bảng mã ký tự.
• Theo chiều ngược lại, Word sang Markdown, HTML sang Markdown và PDF sang Markdown tạo ra Markdown tương thích GitHub: tiêu đề, chữ đậm và nghiêng, danh sách, bảng, liên kết, khối mã và trích dẫn được giữ lại; phông chữ, màu sắc và dàn trang bị bỏ đi. Với bảng không có hàng tiêu đề, hàng đầu tiên sẽ trở thành tiêu đề, vì bảng GFM bắt buộc phải có. Các đoạn văn thường bắt đầu bằng số, như "1. Điều khoản", được thoát ký tự để không vô tình biến thành danh sách. Tệp được lưu dưới dạng UTF-8 không có BOM.

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

Làm sao mở tệp MD?

Trình soạn thảo văn bản nào cũng mở được. Để xem bản đã định dạng, hãy dùng chế độ xem trước của Visual Studio Code hoặc một trình soạn thảo Markdown; nếu muốn đọc trong Word, hãy chuyển tệp sang DOCX.

CommonMark và GitHub Flavored Markdown khác nhau thế nào?

CommonMark định nghĩa cú pháp cốt lõi của Markdown bằng các quy tắc chính xác. GFM là tập mở rộng, bổ sung lên trên CommonMark các phần như bảng, danh sách công việc, gạch ngang chữ và tự động nhận liên kết mở rộng.

Có tạo được bảng trong Markdown không?

Có, với các phần mở rộng như GFM bạn có thể viết bảng đơn giản bằng dấu gạch đứng và gạch ngang. Với cấu trúc phức tạp như ô gộp, hãy dùng bảng HTML hoặc soạn tài liệu trong Word.

Markdown và HTML khác nhau thế nào?

Markdown là định dạng viết đơn giản hơn, được thiết kế để chuyển sang HTML. Nó không diễn đạt được mọi thứ HTML làm được, nhưng dạng thô dễ đọc hơn nhiều. Khi cần, bạn vẫn có thể viết HTML bên trong Markdown.

Markdown có tiêu chuẩn chính thức không?

Mô tả gốc của Gruber không phải là một đặc tả chính thức. Định nghĩa chính xác được chấp nhận rộng rãi nhất hiện nay là CommonMark, và kiểu phương tiện text/markdown đã được RFC 7763 đăng ký vào tháng 3 năm 2016.

Nguồn tham khảo

• John Gruber, Daring Fireball: Markdown
• CommonMark Spec (lịch sử phiên bản)
• GitHub Flavored Markdown Spec
• IETF RFC 7763: The text/markdown Media Type (tháng 3/2016)
• IETF RFC 7764: Guidance on Markdown
• Wikipedia: Markdown (lịch sử, nguồn thứ cấp)
• Markdig: bộ xử lý Markdown tương thích CommonMark cho .NET