Markdown là văn bản thuần biến thành văn bản có định dạng: **đậm** thành chữ đậm, dòng bắt đầu bằng # thành tiêu đề. Nó là mặc định của tệp README, hệ thống quản lý issue, ứng dụng chat, công cụ ghi chú và trình tạo trang tĩnh. Vấn đề là không có một Markdown duy nhất. Bài này giải thích các biến thể chính, cho thấy một trình phân tích xử lý những trường hợp khác nhau thế nào (bằng kết quả thật của trình phân tích đứng sau trình soạn Markdown của chúng tôi), và mô tả quy trình viết không mất bài khi tab trình duyệt bị đóng.
Lịch sử ngắn của các biến thể
John Gruber công bố Markdown năm 2004, với sự giúp sức của Aaron Swartz, gồm một đoạn mã Perl và bản mô tả cú pháp. Bản mô tả bỏ ngỏ nhiều trường hợp (danh sách kết thúc ở đâu? chữ nghiêng có bắt đầu giữa một từ được không?), và mỗi trình phân tích trả lời một kiểu. Hiện nay có ba nhóm đáng quan tâm:
- CommonMark (từ 2014) là đặc tả chính xác với hàng trăm ví dụ, viết ra để chốt các trường hợp bỏ ngỏ. Phần lớn trình phân tích hiện đại theo nó.
- GitHub Flavored Markdown (GFM) là CommonMark cộng phần mở rộng: bảng, danh sách việc cần làm, gạch ngang bằng
~~, và đường dẫn tự thành liên kết. Nhiều công cụ nói "Markdown" thực ra là cái này. - Các phương ngữ mở rộng như Markdown của Pandoc và MultiMarkdown thêm chú thích cuối trang, danh sách định nghĩa, trích dẫn và khối siêu dữ liệu, phổ biến trong xuất bản học thuật và sách.
Nếu viết cho một nền tảng, hãy dùng biến thể của nó. Nếu văn bản phải chạy ở nhiều nơi, hãy giữ phần lõi CommonMark cộng bảng và danh sách việc của GFM, thứ gần như mọi nơi đều hỗ trợ.
Những trường hợp khác nhau, kèm kết quả thật
Các ví dụ sau lấy từ trình phân tích dùng chung giữa trình soạn và công cụ Markdown sang HTML, theo CommonMark ở phần lõi và hỗ trợ các mở rộng GFM phổ biến.
Xuống dòng đơn. Trong CommonMark, một lần xuống dòng giữa đoạn văn là ngắt mềm: hai dòng vẫn là một đoạn, dấu xuống dòng hiển thị như dấu cách. Một số ứng dụng chat biến mọi lần xuống dòng thành <br>. Muốn ngắt dòng chắc chắn ở mọi nơi, hãy kết thúc dòng bằng hai dấu cách: line one␣␣ cho ra line one<br />line two.
Dấu gạch dưới trong từ. snake_case_name giữ nguyên trong CommonMark, vì dấu gạch dưới nằm giữa hai chữ cái không mở chữ nghiêng được. Dấu sao thì được: *a*b cho ra <em>a</em>b. Đoạn mã gốc của Gruber từng làm nghiêng một phần các tên có gạch dưới, nên tài liệu cũ trông như bị lỗi trong công cụ mới.
Bảng và danh sách việc thuộc GFM. Bảng có dòng |:--|--:| cho cột đầu căn trái, cột hai căn phải; - [ ] việc và - [x] xong thành hai ô đánh dấu, ô thứ hai đã tích. Trình phân tích CommonMark thuần không có mở rộng sẽ hiện chúng như chữ thường.
HTML thô. CommonMark cho HTML đi qua; GitHub lọc một số thẻ. Trình phân tích của chúng tôi chặt hơn: <b>hi</b> được hiện như chữ, nên nội dung dán vào không bao giờ chạy được mã.
Chú thích cuối trang và liên kết tham chiếu (text[^1], [ref][x]) là tính năng của Pandoc và MultiMarkdown. Trình phân tích của chúng tôi không hỗ trợ và hiện đúng như bạn gõ; nên biết trước khi viết tài liệu dài dựa vào chúng.
Danh sách thưa và khít. Một dòng trống giữa các mục làm danh sách thưa: mỗi mục được bọc trong thẻ <p> riêng, khoảng cách lớn hơn. Bỏ dòng trống để danh sách gọn lại. Đây là bất ngờ "sao danh sách của tôi giãn thế?" phổ biến nhất.
Quy trình viết không sợ mất bài
Phần lớn bài viết bị mất nằm trong một tab trình duyệt: lỡ tay đóng, trình duyệt treo, máy hết pin, trang tự tải lại sau khi cập nhật. Quy trình chống mất bài có ba lớp.
- Tự lưu tại chỗ khi gõ. Trình soạn lưu văn bản vào bộ nhớ cục bộ của trình duyệt mỗi khi bạn ngừng gõ khoảng nửa giây. Đóng tab, mở lại, bản nháp được khôi phục kèm thông báo. Không có gì gửi lên máy chủ. Hai giới hạn: bản nháp chỉ nằm trong trình duyệt đó trên thiết bị đó, và xóa dữ liệu trang sẽ xóa nó. Một số cửa sổ ẩn danh từ chối lưu; trình soạn báo rõ khi lưu thất bại thay vì im lặng.
- Tải tệp thật ở các mốc quan trọng. Ctrl hoặc ⌘ S tải tệp
.mdđặt tên theo tiêu đề đầu tiên ("Ghi chú họp tuần" thànhghi-chu-hop-tuan.md). Một tệp trong thư mục tài liệu được sao lưu cùng mọi thứ khác và mở được bằng bất kỳ trình soạn văn bản nào sau hai mươi năm. - Xuất định dạng người đọc cần, sau cùng. Trang
.htmlcho web hoặc email, hoặc PDF qua hộp thoại in (trình soạn chỉ in tài liệu đã định dạng, chữ đen nền trắng, tránh ngắt trang giữa bảng và khối mã). Giữ.mdlàm bản gốc; tạo lại tệp xuất từ nó thay vì sửa tệp xuất.
Những lỗi thường gặp
- Trộn biến thể trong một tài liệu. Chú thích viết cho Pandoc hiện thành
[^1]thô trên nhiều nền tảng. Hãy quyết định trước văn bản sẽ được đọc ở đâu. - Dựa vào xuống dòng đơn để ngắt dòng. Chạy ở ứng dụng này, hỏng ở ứng dụng khác. Dùng dòng trống cho đoạn mới và hai dấu cách cuối dòng cho ngắt dòng.
- Thụt lề danh sách con quá ít. Mục con phải thẳng hàng với chữ của mục cha (hai dấu cách sau
-, ba sau1.), nếu không nó thành danh sách riêng. - Viết bài dài trực tiếp trong ô nhập của một trang web. Hầu hết các ô nhập không giữ gì khi tab đóng. Hãy viết nháp trong trình soạn có tự lưu rồi dán sang.
- Coi tự lưu là bản sao lưu. Bộ nhớ cục bộ là lưới an toàn khi trình duyệt treo, không phải kho lưu trữ. Hãy tải tệp xuống.
Thanh công cụ và phím tắt của trình soạn (Ctrl hoặc ⌘ với B, I, K, E) chèn cú pháp giúp bạn, và bản xem trước cho thấy ngay bạn vừa gặp quy tắc nào của biến thể nào.