Markdown là gì? File .md đầy dấu # mở sao cho dễ đọc?

Nói gọn Markdown là gì nhé: đó là cách gõ vài ký hiệu như # hay ** thẳng vào chữ. Mở file trên GitHub hoặc bằng app đọc được Markdown, các dòng ấy hiện thành tiêu đề, chữ đậm và danh sách.

File .md trên máy mở bằng app soạn code miễn phí VS Code sẽ thấy chữ thô trước, bật bản xem trước mới hiện định dạng.

Chắc bạn từng ghé một repo xem file README.md ở đầu trang. Bình thường nhìn rất gọn, nhưng lúc bấm xem chữ thô thì lại thấy toàn dấu #, chữ kẹp giữa ** hay dòng - [ ].

Khi chép câu trả lời chatbot sang khung chat khác, hoặc mở file .md tải về bằng app soạn văn bản, đám dấu đó cũng lộ ra. Hồi mới gặp, Tuấn tưởng file lỗi phông chữ.

Thật ra file không hỏng đâu: bài này giúp bạn đọc quen các dấu hay gặp và mở file .md hiện định dạng sáng sủa.

1. Markdown là gì? Gõ chữ kèm ký hiệu, app hiểu Markdown sẽ hiện trang gọn

Trên trang của người tạo ra Markdown, tên này gọi chung hai thứ.

Một là bộ ký hiệu gõ thẳng vào chữ thô. Hai là phần mềm viết bằng Perl đổi chữ đó sang HTML để trình duyệt hiện trang web.

MarkItDown là công cụ đổi file sang Markdown của Microsoft. Ở README của repo MarkItDown, bạn thấy ngay dấu #, >, - đầu dòng khi bấm nút Code mở chữ thô theo mục 3.

Nguồn: github.com/microsoft/markitdown

Mục tiêu khi thiết kế Markdown là để nguyên chữ thô đọc vẫn xuôi, nhìn không giống đoạn chữ bị chèn đầy thẻ kiểu <p> hay lệnh định dạng. Markdown không hứa ai mới nhìn lần đầu cũng hiểu hết mọi dấu, nhưng Tuấn rất thích vì mở chữ thô ra vẫn thoáng mắt.

Dù lúc lên trang có đủ tiêu đề, chữ đậm lẫn bảng, bản thân file .md không giấu thêm lớp định dạng nào ngoài những dòng bạn gõ.

Đôi lúc đọc README thấy xen vài thẻ HTML, tức thẻ giúp trình duyệt hiển thị trang web, bạn cũng đừng lạ. Chỗ nào Markdown chưa có cách gõ, người viết cứ gõ thẳng thẻ HTML xen vào file mà không cần khai báo hay đánh dấu riêng; chỉ lưu ý là khối HTML vẫn có vài quy định đặt riêng trong file.

1.1 Ai tạo ra Markdown, sao có nhiều kiểu Markdown

John Gruber tạo ra Markdown năm 2004, có Aaron Swartz góp ý thêm. Hiện Markdown gốc vẫn lưu tại trang giới thiệu Markdown của John Gruber.

Phần mềm của Gruber nhanh chóng được nhiều trang web đem về dùng. Về sau có thêm hàng chục phần mềm khác tự làm lại bộ chuyển Markdown bằng nhiều ngôn ngữ khác nhau, nhưng kết quả hiện định dạng giữa các bên lại lệch nhau.

Phần mềm của Gruber là phần mềm tự do, mở miễn phí theo giấy phép kiểu BSD của mã nguồn mở. Bản thân việc gõ Markdown cũng không mất tiền, bạn chỉ trả phí nếu chọn mua riêng một app đọc file có thu phí.

Sở dĩ các phần mềm trên hiện lệch nhau là do mô tả gốc của Gruber chưa định nghĩa cách gõ thật rõ, còn phần mềm của Gruber lại nhiều lỗi. Thành ra cùng một file nhưng mở ở chỗ khác nhau lại hiện khác nhau.

Để gỡ cảnh đó, đặc tả chuẩn chung CommonMark ra đời nhằm quy định chặt từng ký hiệu. Nhờ vậy, cùng một file mở trên các phần mềm theo CommonMark sẽ hiện khớp nhau.

Riêng GitHub dùng GFM, viết tắt của GitHub Flavored Markdown: nó dựa trên CommonMark, giữ đủ mọi cách gõ của CommonMark rồi thêm vài cách gõ riêng ở mục 5. Nắm điểm này, bạn sẽ hiểu sao có bảng hiện mượt trên GitHub mà qua app khác lại chỉ thấy chữ thô.

2. File Markdown là gì? Đuôi .md và .markdown

Mới tải tài liệu trên GitHub về máy, nhiều bạn thấy cái đuôi lạ nên hay nhắn hỏi Tuấn file md là gì.

Thật ra file mang đuôi .md hoặc .markdown là một file chữ ghi nội dung gõ bằng Markdown. Vì bên trong chỉ có chữ và các ký hiệu, bạn dùng app soạn văn bản nào mở lên đọc cũng được.

Trên máy Mac cũng vậy: macOS nhận sẵn file .md là tài liệu Markdown thuộc nhóm file chữ, nên chưa cài thêm gì bạn vẫn mở xem ngay bằng app có sẵn như TextEdit.

File nhẹ hều nên Tuấn rất chuộng dùng để lưu ghi chú hằng ngày, còn chuyện mở bằng app nào cho đẹp mắt thì tới mục 6 mình bàn kỹ nhé.

3. README.md trên GitHub: trang thì gọn, chữ thô lại có dấu #

Khi mở một repo trên GitHub, tức trang chứa mã nguồn và tài liệu của dự án, file bạn thấy đầu tiên thường là README.md. File này kể gọn dự án làm gì, bắt đầu dùng thế nào và ai đang phụ trách.

Bạn ghé xem repo thì khỏi mất công lục từng thư mục, vì GitHub luôn tự đưa nội dung README này hiện thẳng ngay mặt trang.

Bạn nhìn thử README của repo MarkItDown trên GitHub sẽ thấy trang đã hiện định dạng sẵn cả tiêu đề lẫn hộp lưu ý. Ngay góc trên khung xem file có hai nút Preview và Code để đổi cách xem.

Nguồn: github.com/microsoft/markitdown

Khi mở chữ thô của đúng file README đó, bạn chỉ cần nhìn các ký hiệu đầu dòng chứ khỏi dịch đoạn tiếng Anh; riêng > [!IMPORTANT] là dấu mở hộp lưu ý sẽ kể ở mục 5:

# MarkItDown

[![PyPI](https://img.shields.io/pypi/v/markitdown.svg)](https://pypi.org/project/markitdown/)
![PyPI - Downloads](https://img.shields.io/pypi/dd/markitdown)

> [!IMPORTANT]
> MarkItDown performs I/O with the privileges of the current process. Like open() or requests.get(), it will access resources that the process itself can access. Sanitize your inputs in untrusted environments, and call the narrowest `convert_*` function needed for your use case (e.g., `convert_stream()`, or `convert_local()`). See the [Security Considerations](#security-considerations) section of the documentation for more information.

Muốn xem phần chữ thô đầy dấu # và > đó trên web, bạn bấm nút Code ở góc trên khung file để ẩn lớp hiện định dạng. Xem xong, bấm lại Preview ngay cạnh là quay về bản đã hiện định dạng.

GitHub cũng tự tạo mục lục từ các tiêu đề trong file, nhưng chỉ mở ra khi bạn bấm nút Outline ở góc trên trang. Gặp README dài, Tuấn toàn bấm Outline để nhảy thẳng tới mục cần đọc.

4. Cú pháp Markdown cơ bản đủ để đọc README

Bạn không cần học như học lập trình đâu, vì đọc README chỉ xoay quanh chừng chục dấu cơ bản. Gặp nhiều nhất là dấu # đặt đầu dòng để chia tiêu đề từ lớn tới nhỏ.

Nguồn: docs.github.com

Riêng tiêu đề, sau dấu # cuối phải cách một khoảng trắng: gõ # Tiêu đề mới ra tiêu đề, còn viết dính liền #Tiêu đề thì không nhận. Trong README, bạn chủ yếu gặp 10 cách gõ cơ bản này:

Ở hai hàng cuối, bạn nhớ gõ ngoặc tròn sát ngay sau ngoặc vuông như [chữ](địa-chỉ), không để khoảng trắng chen giữa.

Ghép các dấu này vào một file .md thật thì trông thế nào?

Ngoài mười cách gõ trên, lúc viết bạn nhớ chừa một dòng trống ngăn giữa hai dòng chữ để sang đoạn mới. Còn cần GitHub giữ nguyên dấu # hay * mà không đổi thành định dạng, bạn đặt dấu gạch chéo ngược \ (backslash) ngay trước nó.

Ghép các ký hiệu ấy vào một file README.md mẫu thì chữ thô trông như vầy:

# Tên dự án

Công cụ **chuyển PDF** sang chữ, viết bằng *Python*.

## Cài đặt

1. Tải mã về máy
2. Chạy lệnh `pip install -r requirements.txt`

- [x] Đọc file PDF
- [ ] Đọc file Word

| Lệnh | Việc |
|:--|:--|
| `run` | Chạy |

~~Bản cũ~~ · Xem [trang hướng dẫn](https://example.com).

Khi đọc theo GFM, GitHub hiện định dạng file mẫu này thành tiêu đề lớn nhỏ, chữ đậm, danh sách số, bảng và link. Hai dòng [x] và [ ] cũng đổi tương ứng thành ô đã tick và ô trống.

Lúc nào quên một dấu nhỏ khi đọc README, bạn chỉ cần mở lại bảng vừa rồi hoặc tra thêm trên hướng dẫn cách gõ định dạng trên GitHub là đọc thông suốt ngay.

5. GitHub Flavored Markdown thêm gì: bảng, danh sách việc có ô tick, hộp lưu ý

Ngay từ Markdown gốc đã có gạch đầu dòng và danh sách đánh số để bạn liệt kê đầu việc, chỉ là chưa có ô tick bên cạnh. Đến GFM mới có thêm ô tick, bảng, chữ gạch ngang bằng dấu ~ và tự biến địa chỉ web thành link; riêng hộp lưu ý do trang GitHub làm thêm.

Trong file README.md mẫu ở mục 4, hai dòng - [x] và - [ ] chính là chỗ tạo ô tick, còn các dấu gạch đứng | dùng để kẻ bảng.

Riêng hộp lưu ý không nằm trong đặc tả GFM, nên app khác dù đọc được GFM vẫn có thể không hiện. Đây là phần GitHub mở rộng riêng dựa trên dấu trích dẫn > với 5 kiểu hộp lưu ý.

Năm kiểu này viết là > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING] và > [!CAUTION]. Khi lên GitHub, mỗi hộp sẽ hiện màu và biểu tượng riêng như khung IMPORTANT ở mục 3.

Vậy mang file có dòng [x] sang chỗ khác mở thì sao?

Ở nơi chỉ đọc Markdown gốc mà không hiểu GFM, dòng - [x] Đọc file PDF sẽ giữ nguyên chữ [x] chứ không biến thành ô tick. Khi nào cần tra xem đặc tả quy định những ký hiệu nào, bạn mở tài liệu chuẩn GFM của GitHub là rõ nhất.

Các cách gõ GFM này dùng được cả ở ô bình luận lẫn issue, tức chỗ báo lỗi và góp ý của repo trên web GitHub. Tuấn rất hay gõ - [ ] vào bình luận để rà đầu việc khỏi sót.

6. Mở file md bằng gì cho dễ đọc

Là file chữ nên file .md mở xem chữ thô ở app nào cũng được, nhưng muốn thấy hiện định dạng rõ ràng thì bạn cần mở bằng trang web hoặc app đọc được Markdown.

File đang nằm trong repo thì bạn xem thẳng trên GitHub là tiện nhất, còn file đã tải về máy thì dùng VS Code để thấy hiện định dạng.

6.1 Xem ngay trên GitHub, không cần cài gì

Với bất kỳ file .md nào nằm trong repo công khai trên github.com, bạn chỉ cần bấm vào tên file là GitHub hiện định dạng sẵn tiêu đề, chữ đậm và danh sách mà không đòi đăng nhập.

Còn lúc cần chép phần chữ thô về máy, bạn chuyển qua nút Code theo cách ở mục 3.

Muốn lưu bản sao về máy đọc lúc mất mạng, bạn làm theo cách tải file từ GitHub về máy là gọn nhất. Còn khi chỉ tra cứu nhanh, Tuấn vẫn thích đọc thẳng trên web cho đỡ chật thư mục tải về.

6.2 VS Code: app soạn code miễn phí, bật xem trước file .md

File trên máy thì bạn mở bằng VS Code: app soạn code mã nguồn mở, dùng riêng hay cho việc kinh doanh đều miễn phí. Cài xong là bật bản xem trước file .md được ngay, khỏi cài thêm gì.

Nguồn: code.visualstudio.com

Để mở file md thành trang dễ nhìn trong VS Code, bạn làm đúng ba bước ngắn:

1. Tải VS Code tại code.visualstudio.com về cài, rồi mở app chọn File > Open tới file .md. Mở từ thư mục thì trên Mac giữ Control bấm vào file, chọn Open With rồi chọn VS Code; còn ở máy Windows bạn bấm chuột phải lên file, vào Open with > Choose another app để chọn VS Code.
2. Trên Mac, giữ Shift ⇧ và Command ⌘ rồi bấm V để sang bản xem trước; trên Windows hoặc Linux thì bấm Ctrl+Shift+V.
3. Muốn đặt bản xem trước cạnh chữ thô, trên Mac bấm Command ⌘ + K, nhả ra rồi bấm V; trên Windows và Linux bấm Ctrl+K rồi V. Bạn gõ sửa bên khung chữ thô tới đâu là bản xem trước cập nhật theo ngay.

Theo Tuấn, bạn cứ dùng bản xem trước ở trên là ổn định nhất. Xem thêm tài liệu Markdown của VS Code, bạn sẽ gặp mục Markdown Editor giúp gõ sửa ngay trên trang đã hiện định dạng, khỏi chuyển qua bản xem trước.

Tuấn khuyên khoan dùng vì Markdown Editor mới đang thử nghiệm. Ở các bản cập nhật sau, bên làm VS Code có thể đổi lại hoặc bỏ luôn tính năng này.

6.3 Notepad trên Windows 11

Theo bài Microsoft công bố bản Notepad mới, app Notepad trên Windows 11 đã có bản thử nghiệm hiện định dạng cho file Markdown, gửi trước tới người dùng Windows Insider. Windows Insider là chương trình cho người dùng đăng ký trải nghiệm sớm các bản Windows và Notepad mới.

Notepad bản này nhận cả file .md lẫn .markdown. Bạn đổi qua lại giữa bản đã hiện định dạng và chữ thô qua menu View, hoặc bấm nút ở thanh trạng thái dưới đáy cửa sổ.

Nếu chỉ quen nhìn chữ thô như trước, bạn vẫn tắt hẳn tính năng hiện định dạng đi được ngay trong cài đặt của app Notepad.

Nguồn: Windows Insider Blog

Trên Windows 11 bản thường không tham gia Windows Insider, chưa rõ tính năng này đã có chưa; bạn cứ mở thử file .md bằng Notepad rồi nhìn đáy cửa sổ.

Nếu chưa thấy nút ở thanh trạng thái, theo Tuấn bạn cứ cài VS Code như mục 6.2 cho chủ động khỏi chờ.

6.4 TextEdit trên Mac và app soạn văn bản: khi nào thấy nguyên ký hiệu?

Mở file .md bằng TextEdit trên máy Mac, bạn sẽ thấy cửa sổ bày ra phần chữ thô đúng như lúc người viết gõ.

Đó là vì các app soạn văn bản như TextEdit trên Mac hay Notepad đời cũ vốn không đọc Markdown để hiện định dạng, nên chỉ mở nội dung ra y hệt khối ký hiệu của file mẫu ở mục 4.

Dù còn nguyên ký hiệu trên dòng, mặt chữ nhìn vẫn khá thoáng mắt. Gặp mấy file ghi chú ngắn vài chục dòng, Tuấn toàn đọc thẳng chữ thô như vậy luôn cho lẹ.

7. Markdown trong AI: prompt, câu trả lời của chatbot, file SKILL.md

Khi dùng các công cụ AI hằng ngày, bạn cũng gặp Markdown trong cả prompt gửi đi, câu trả lời của chatbot lẫn file SKILL.md của trợ lý AI.

Theo hướng dẫn viết prompt của OpenAI, khi nhắn cho AI bạn có thể kết hợp tiêu đề, danh sách Markdown với thẻ XML để chia phần. Cách trình bày này giúp mô hình AI nhận ra đâu là từng phần riêng và phần nào nằm trong phần nào.

Mỗi lần viết prompt dài quá nửa trang, Tuấn đều chia mục bằng dấu # và gạch - vì chính mình đọc soát lại cũng đỡ sót ý hẳn.

Còn lúc AI trả lời, tài liệu OpenAI cho người làm app ghi rõ: từ bản o1-2024-12-17, tức mô hình o1 ngày 17 tháng 12 năm 2024 trở đi, dòng mô hình suy luận của hãng gọi qua API sẽ mặc định tránh Markdown. Bên làm app muốn có định dạng mới bật lại, và quy định này chỉ áp khi gọi API chứ không phải cài đặt trong khung ChatGPT.

Từ chuyện này, Tuấn suy ra các chatbot vốn quen trả lời bằng Markdown nên OpenAI mới phải đặt riêng quy định tắt đi rồi chỉ cách bật lại. Tất nhiên đây là điều Tuấn tự suy ra chứ tài liệu hãng không nói thẳng.

File SKILL.md và công cụ chuyển tài liệu cho AI dùng Markdown ra sao?

Markdown cũng có mặt khi bạn gắn thêm skill cho trợ lý AI. Hiểu gọn thì mỗi skill là một thư mục chứa lời chỉ dẫn giúp trợ lý AI đảm nhận một đầu việc, và theo đặc tả thì thư mục đó tối thiểu phải có file SKILL.md.

Đầu file SKILL.md là vài dòng khai báo tên và mô tả skill, còn phần thân bên dưới viết bằng Markdown để dặn trợ lý AI cách làm.

Khi cần đổi tài liệu có sẵn cho AI dùng, công cụ mã nguồn mở tại repo MarkItDown của Microsoft giúp chuyển file PDF, Word, Excel, PowerPoint sang Markdown và cố giữ nguyên cấu trúc tiêu đề, danh sách lẫn bảng biểu.

8. Có cần học Markdown không

Khi đã hiểu rõ Markdown là gì, hẳn bạn sẽ tự hỏi người không làm lập trình như mình có cần bỏ thời gian học gõ đám dấu này hay không.

• Chỉ cần đọc: Nếu bạn chỉ ghé repo xem tài liệu, đọc câu trả lời chatbot hay mở file .md tải về thì khỏi cần học gõ ký hiệu. Muốn xem bản đã hiện định dạng cho êm mắt, bạn cứ mở trên GitHub hoặc bật bản xem trước trong VS Code.
• Nên tập viết: Nếu bạn hay viết prompt dài chia phần, ghi chú, sửa file SKILL.md hay làm README nhỏ, tập gõ vài lần sẽ rất tiện. Bạn chỉ cần nhớ vài hàng ở bảng mục 4 như tiêu đề # chữ, đậm **chữ**, gạch -, ` lệnh và link viết sát [chữ](địa-chỉ)` là đủ dùng.

Hy vọng sau cuộc trò chuyện nhỏ này, mấy dấu # hay ** không còn làm bạn ngán mắt mỗi lần mở một file .md lạ nữa.

Hiện bạn đang gặp file .md hay trang README nào nhiều ký hiệu làm mình rối nhất, cứ kể ở phần bình luận để Tuấn xem phụ bạn nhé?