Bảng tra cứu cú pháp Markdown: từng nhóm lệnh, ví dụ và chỗ hay sai
Bảng tra cứu cú pháp Markdown gom theo tám nhóm quen dùng nhất: tiêu đề, định dạng chữ, danh sách, liên kết và ảnh, khối mã, bảng, trích dẫn và đường kẻ ngang. Mỗi mục có sẵn cú pháp mẫu kèm một ví dụ thật, gõ vào ô tìm kiếm là lọc ngay, bấm một nút là chép được đoạn cú pháp vào clipboard.
Tính năng nổi bật
- Tám nhóm cú pháp: Headings, Text Formatting, Lists, Links và Images, Code Blocks, Tables, Blockquotes, Horizontal Rules
- Mỗi mục hiển thị song song cột cú pháp và cột ví dụ áp dụng thật
- Ô tìm kiếm lọc theo tên mục lẫn theo chính chuỗi cú pháp
- Nút sao chép từng mục, chép nguyên đoạn cú pháp vào clipboard
- Có cả cú pháp mở rộng của GitHub như task list và gạch ngang chữ
- Bảng có cả biến thể căn lề trái, giữa, phải bằng dấu hai chấm
- Cú pháp nhiều dòng giữ nguyên xuống dòng khi sao chép
- Toàn bộ dữ liệu nằm sẵn trong trang, không gọi máy chủ khi tra cứu
Markdown dễ học nhưng khó nhớ hết, và sai một ký tự là hỏng cả khối
Markdown chỉ có vài chục ký hiệu, nhưng phần lớn người dùng chỉ thuộc bốn hoặc năm cái hay gõ nhất: dấu thăng cho tiêu đề, hai dấu sao cho chữ đậm, dấu gạch ngang cho danh sách. Đến lúc cần một bảng có căn lề, một task list, hay một khối mã lồng trong mục danh sách thì phải đi tìm lại. Cái khó của Markdown không nằm ở việc hiểu ý nghĩa mà nằm ở khoảng trắng và dòng trống: thiếu một dòng trống trước danh sách thì cả danh sách dính vào đoạn văn phía trên, thụt lề hai khoảng trắng thay vì bốn thì mục con không lồng vào đúng cấp, quên dòng dấu gạch ngang dưới hàng tiêu đề thì bảng không thành bảng mà hiện ra thành một dòng chữ đầy dấu sổ đứng. Có sẵn một bảng tra cứu chuẩn để chép nguyên đoạn cú pháp rồi thay chữ vào giúp bạn bỏ qua toàn bộ nhóm lỗi khoảng trắng đó.
Lợi ích khi sử dụng
- Chép đúng khuôn cú pháp nên không dính lỗi thiếu khoảng trắng hay thiếu dòng trống
- Xem được cú pháp và ví dụ cạnh nhau nên hiểu ngay chỗ nào là ký hiệu, chỗ nào là nội dung thay được
- Tìm bằng từ khóa nhanh hơn cuộn tài liệu dài hoặc mở lại trang tài liệu của GitHub
- Có sẵn cả cú pháp mở rộng như task list và bảng căn lề, những thứ Markdown gốc không có
- Tra cứu ngay trong trình duyệt khi đang viết README hoặc tài liệu, không phải cài thêm gì
Cách tra cứu cú pháp Markdown
- 1Gõ từ khóa vào ô tìm kiếm, ví dụ table, bold hay code, để lọc thẳng tới mục cần dùng thay vì cuộn qua cả tám nhóm.
- 2Đọc cột Syntax bên trái để lấy khuôn cú pháp, và cột Example bên phải để xem khuôn đó trông ra sao khi điền nội dung thật.
- 3Bấm nút sao chép ở góc phải của mục để chép nguyên đoạn cú pháp, kể cả phần nhiều dòng như bảng hay khối mã.
- 4Dán vào trình soạn thảo của bạn rồi thay chữ mẫu bằng nội dung thật, giữ nguyên các ký hiệu và mức thụt lề.
- 5Xem lại bằng chế độ xem trước của chính nền tảng đích, vì mỗi nền tảng hỗ trợ một tập cú pháp mở rộng khác nhau.
Ba lỗi khoảng trắng làm hỏng khối Markdown nhiều nhất
Lỗi thứ nhất là thiếu dòng trống ngăn cách. Markdown coi các dòng liền nhau là cùng một đoạn văn, nên nếu bạn viết một câu rồi xuống dòng gõ ngay dấu gạch ngang, danh sách sẽ bị nuốt vào đoạn văn phía trên. Luôn chừa một dòng trống trước và sau mỗi khối danh sách, bảng, khối mã hay trích dẫn. Lỗi thứ hai là xuống dòng không ăn. Trong Markdown, nhấn Enter một lần chỉ ngắt dòng trong mã nguồn chứ không tạo thẻ xuống dòng khi hiển thị; muốn xuống dòng trong cùng một đoạn bạn phải để hai khoảng trắng ở cuối dòng trước, hoặc dùng thẳng thẻ br. Lỗi thứ ba là thụt lề sai cấp cho danh sách lồng nhau. Mục con phải thụt vào đúng bằng chiều rộng của dấu đầu dòng cha cộng khoảng trắng theo sau, thường là hai ký tự với danh sách gạch ngang và ba ký tự với danh sách đánh số. Trộn tab với khoảng trắng trong cùng một danh sách là cách nhanh nhất để cấu trúc lồng nhau vỡ hoàn toàn.
Bảng trong Markdown: dòng phân cách quyết định tất cả
Một bảng Markdown tối thiểu cần ba thành phần theo đúng thứ tự: hàng tiêu đề, hàng phân cách bằng dấu gạch ngang, rồi mới tới các hàng dữ liệu. Thiếu hàng phân cách thì toàn bộ khối không được nhận là bảng. Số cột của hàng phân cách phải bằng số cột của hàng tiêu đề, nếu lệch thì phần dư bị bỏ hoặc bảng vỡ. Căn lề nằm ở chính hàng phân cách: hai chấm ở đầu là căn trái, hai chấm ở cả hai đầu là căn giữa, hai chấm ở cuối là căn phải. Số dấu gạch ngang không ảnh hưởng kết quả, ba dấu hay hai mươi dấu đều cho ra cùng một bảng, nên bạn không cần canh cho các dấu sổ đứng thẳng hàng dù canh thẳng thì mã nguồn dễ đọc hơn. Markdown thuần không hỗ trợ gộp ô, xuống dòng bên trong ô hay bảng lồng bảng. Muốn có những thứ đó bạn phải chèn HTML, và cần chấp nhận rằng một số nơi hiển thị Markdown sẽ lọc bỏ HTML vì lý do bảo mật.
Khối mã: dấu huyền ba lần, tên ngôn ngữ và trường hợp phải dùng bốn dấu
Có hai cách tạo khối mã. Cách cũ là thụt lề toàn khối vào bốn khoảng trắng, nay ít dùng vì dễ va với danh sách lồng nhau. Cách phổ biến là bọc khối bằng ba dấu huyền ở dòng trên và dòng dưới. Ghi tên ngôn ngữ ngay sau ba dấu huyền mở, ví dụ js, python, bash, json, để trình hiển thị tô màu cú pháp; ghi sai tên ngôn ngữ thì phần lớn trình hiển thị chỉ bỏ qua tô màu chứ không báo lỗi. Trường hợp hay làm người viết tài liệu bối rối là khi bản thân đoạn mã cần hiển thị lại chứa ba dấu huyền, chẳng hạn khi bạn viết hướng dẫn về chính Markdown. Lúc đó hãy bọc ngoài bằng bốn dấu huyền, khối bên trong ba dấu sẽ được hiển thị nguyên văn. Với mã ngắn nằm giữa câu, dùng một dấu huyền hai bên; nếu đoạn mã đó có chứa dấu huyền thì bọc bằng hai dấu huyền và chừa một khoảng trắng ở hai đầu.
Markdown gốc, CommonMark và bản mở rộng của GitHub khác nhau ra sao
Markdown ra đời năm 2004 với một bản đặc tả khá lỏng, dẫn tới việc mỗi trình xử lý hiểu một kiểu ở các trường hợp biên. CommonMark là nỗ lực chuẩn hóa lại bằng một đặc tả chặt kèm bộ kiểm thử, và ngày nay phần lớn thư viện mới đều bám theo CommonMark. GitHub Flavored Markdown xây trên nền CommonMark rồi bổ sung một số thứ mà bản gốc không có: bảng, task list dạng ô đánh dấu, gạch ngang chữ bằng hai dấu ngã, tự động nhận diện đường dẫn thành liên kết. Bảng tra cứu này gom cả nhóm cú pháp lõi lẫn nhóm mở rộng phổ biến đó. Hệ quả thực tế là một tệp Markdown chạy đẹp trên GitHub chưa chắc hiển thị y hệt ở nơi khác: nhiều diễn đàn và ứng dụng chat chỉ hỗ trợ một tập rất hẹp, còn chú thích chân trang hay danh sách định nghĩa thì chỉ có ở vài bản mở rộng riêng. Trước khi dùng một cú pháp lạ cho tài liệu quan trọng, hãy thử trước trên đúng nền tảng sẽ hiển thị nó.
Thoát ký tự và những chỗ Markdown hiểu nhầm ý bạn
Vì Markdown gán ý nghĩa cho các ký tự vốn hay xuất hiện trong văn bản thường, sẽ có lúc bạn muốn hiển thị đúng ký tự đó chứ không phải hiệu ứng của nó. Cách xử lý là đặt một dấu gạch chéo ngược ngay trước ký tự cần thoát. Nhóm ký tự cần để ý gồm dấu sao, gạch dưới, thăng, ngoặc vuông, ngoặc đơn, dấu huyền, dấu gạch ngang và dấu chấm sau số ở đầu dòng. Trường hợp thực tế hay gặp nhất là tên biến hoặc tên tệp có nhiều dấu gạch dưới: viết thẳng thì phần giữa hai dấu gạch dưới biến thành chữ nghiêng và hai dấu gạch dưới biến mất, làm sai tên biến trong tài liệu kỹ thuật. Cách gọn nhất trong tình huống này không phải thoát từng ký tự mà là bọc cả cụm trong dấu huyền để nó thành mã nội dòng, vừa đúng ngữ nghĩa vừa dễ đọc. Một chỗ khác dễ vấp là dòng bắt đầu bằng một con số kèm dấu chấm, chẳng hạn một năm như 2024 đứng đầu dòng, sẽ bị hiểu thành danh sách đánh số.
Câu hỏi thường gặp (FAQ)
Trang này có xem trước kết quả render không?
Không. Bảng tra cứu hiển thị hai cột đều là văn bản mã: cột Syntax là khuôn cú pháp và cột Example là một ví dụ đã điền nội dung. Bạn xem để hiểu cách viết rồi chép sang trình soạn thảo của mình, còn phần xem trước kết quả thì dùng chính trình soạn thảo hoặc nền tảng đích.
Xuống dòng trong Markdown mà không tạo đoạn mới thì làm sao?
Gõ hai khoảng trắng ở cuối dòng rồi nhấn Enter, hoặc chèn thẻ br. Nhấn Enter một lần không đủ vì Markdown gộp các dòng liền nhau thành một đoạn. Nhấn Enter hai lần sẽ tạo một đoạn văn mới, cách này đúng khi bạn thật sự muốn ngắt đoạn chứ không phải chỉ xuống dòng.
Danh sách lồng nhau phải thụt vào bao nhiêu khoảng trắng?
Thụt vào bằng đúng chiều dài dấu đầu dòng của mục cha cộng khoảng trắng theo sau nó. Với danh sách gạch ngang thì thường là hai khoảng trắng, với danh sách đánh số dạng một chấm cách thì là ba. Bốn khoảng trắng cũng chạy ở phần lớn trình xử lý, nhưng quan trọng nhất là dùng nhất quán một mức trong cả tài liệu.
Task list gõ thế nào và chỗ nào hỗ trợ?
Viết dấu gạch ngang, khoảng trắng, rồi cặp ngoặc vuông chứa một khoảng trắng cho mục chưa xong, hoặc chứa chữ x cho mục đã xong. Đây là cú pháp mở rộng của GitHub, chạy trên GitHub, GitLab và nhiều công cụ ghi chú, nhưng không có trong Markdown gốc nên một số nơi sẽ hiện ra đúng dạng ngoặc vuông thô.
Bảng của tôi hiện ra thành một dòng chữ đầy dấu sổ đứng, vì sao?
Gần như luôn là do thiếu hàng phân cách bằng dấu gạch ngang ngay dưới hàng tiêu đề, hoặc số cột của hàng phân cách không khớp với hàng tiêu đề. Nguyên nhân thứ hai là thiếu dòng trống ngăn bảng với đoạn văn phía trên. Nguyên nhân thứ ba là nền tảng đó không hỗ trợ bảng vì đây là cú pháp mở rộng.
Làm sao chèn khối mã bên trong một mục danh sách?
Thụt cả khối mã vào cùng mức thụt lề với phần nội dung của mục danh sách, thường là hai hoặc bốn khoảng trắng, kể cả hai dòng ba dấu huyền mở và đóng. Nếu để ba dấu huyền sát lề trái, trình xử lý sẽ coi khối mã nằm ngoài danh sách và mục danh sách bị cắt làm đôi tại đó.
Chèn HTML thẳng vào Markdown được không?
Phần lớn trình xử lý cho phép, và đây là cách duy nhất để có những thứ Markdown không hỗ trợ như gộp ô bảng hay căn chỉnh ảnh. Nhưng nhiều nền tảng lọc bỏ HTML vì lý do bảo mật, đặc biệt là thẻ script, style và các thuộc tính sự kiện. Tài liệu cần chạy được ở nhiều nơi thì nên hạn chế HTML.
Tên biến có dấu gạch dưới bị biến thành chữ nghiêng, xử lý thế nào?
Bọc cả cụm trong một cặp dấu huyền để biến nó thành mã nội dòng. Cách này vừa giữ nguyên dấu gạch dưới vừa đúng ngữ nghĩa vì đó là tên biến. Nếu bắt buộc phải để dạng chữ thường, đặt dấu gạch chéo ngược trước từng dấu gạch dưới, nhưng cách này khiến mã nguồn khó đọc hơn hẳn.
Muốn hiển thị chính ba dấu huyền trong khối mã thì làm sao?
Bọc khối ngoài bằng bốn dấu huyền thay vì ba. Trình xử lý sẽ lấy hàng rào dài hơn làm ranh giới, nên nội dung ba dấu huyền bên trong được hiện nguyên văn. Nguyên tắc chung là hàng rào ngoài phải nhiều dấu huyền hơn bất kỳ chuỗi dấu huyền nào xuất hiện trong nội dung.
Ba cách viết đường kẻ ngang có khác nhau không?
Ba dấu gạch ngang, ba dấu sao và ba dấu gạch dưới đều cho ra cùng một đường kẻ ngang. Chỉ có một lưu ý thực tế: ba dấu gạch ngang đặt ngay dưới một dòng chữ sẽ bị hiểu thành tiêu đề cấp hai theo kiểu gạch chân chứ không phải đường kẻ, nên hãy chừa dòng trống phía trên hoặc dùng ba dấu sao cho chắc.
Đặt chữ thay thế cho ảnh trong Markdown có quan trọng không?
Có. Phần chữ trong cặp ngoặc vuông của cú pháp ảnh chính là thuộc tính alt khi chuyển sang HTML, phục vụ người dùng trình đọc màn hình và hiển thị khi ảnh lỗi. Nhiều người để trống hoặc ghi image, cả hai đều làm mất thông tin. Hãy mô tả ngắn nội dung ảnh bằng một cụm từ có nghĩa.
Nội dung tôi tìm kiếm trên trang có được gửi đi đâu không?
Không. Toàn bộ danh mục cú pháp nằm sẵn trong trang, thao tác tìm kiếm chỉ là lọc danh sách ngay trong trình duyệt và nút sao chép ghi thẳng vào clipboard của máy bạn. Trang không gửi từ khóa hay nội dung nào lên máy chủ trong quá trình bạn tra cứu.
Từ khóa liên quan
- markdown cheatsheet
- cú pháp markdown
- bảng tra cứu markdown
- markdown là gì
- cách viết markdown
- markdown table
- tạo bảng trong markdown
- markdown code block
- markdown xuống dòng
- markdown danh sách lồng nhau
- task list markdown
- github flavored markdown
- commonmark
- markdown syntax guide
- viết readme markdown
- markdown chèn ảnh
- markdown chèn link
- escape ký tự trong markdown
- markdown blockquote
- hướng dẫn markdown tiếng việt
