Bảng Tra Cứu Markdown

Về Bảng Tra Cứu Markdown

CommonMark và GitHub Flavored Markdown khác nhau ra sao?

CommonMark là đặc tả Markdown rõ ràng công bố năm 2014, giải quyết hàng chục trường hợp biên còn mơ hồ trong bản gốc của John Gruber năm 2004. GitHub Flavored Markdown (GFM) là tập cha nghiêm ngặt của CommonMark - mọi thứ CommonMark hỗ trợ thì GFM cũng hỗ trợ y hệt, và GFM thêm bảng, danh sách công việc, gạch ngang, liên kết tự động cùng vài luật bổ sung. Các tính năng mới hơn riêng của GitHub như callout (> [!NOTE]), phần thu gọn, mã hàng rào tô màu và mã emoji không hẳn thuộc GFM nhưng GitHub vẫn render. Bảng tra cứu này gọi chúng là 'Tiện ích GFM' cho gọn, nhưng hãy nhớ không phải engine Markdown nào cũng render được; với tài liệu cần tính di động cao hãy dùng CommonMark thuần.

Vì sao danh sách của tôi không render đúng?

Lỗi render Markdown phổ biến nhất là thiếu dòng trống ngăn danh sách với đoạn văn liền trước. CommonMark yêu cầu dòng trống trước bất kỳ danh sách nào, nếu không mục đầu sẽ dính vào văn bản trước thành một đoạn. Lỗi thứ hai phổ biến là thụt lề lồng: mỗi cấp phải thụt đúng bằng độ rộng dấu đầu mục cộng một dấu cách (thường hai dấu cách cho danh sách không thứ tự, ba hoặc bốn cho danh sách có thứ tự). Nếu mục con không chịu thụt vào, kiểm tra rằng dòng cha không kết thúc bằng dấu cách thừa và bạn dùng dấu cách chứ không phải tab. Cuối cùng, một số trình phân tích cũ không chấp nhận số khác 1 làm mục đầu tiên của danh sách có thứ tự; CommonMark chấp nhận mọi số và vẫn render theo thứ tự.

Làm sao thoát các ký tự đặc biệt của Markdown?

Đặt dấu gạch chéo ngược trước bất kỳ ký tự nào Markdown sẽ diễn dịch: \*không nghiêng\*, \#không-là-tiêu-đề, \[không-là-liên-kết\]. Các ký tự có thể thoát: \ ` * _ { } [ ] ( ) # + - . ! | > và ~. Ngoài chúng, dấu gạch chéo ngược giữ nguyên. Trường hợp tinh tế hơn là backtick bên trong mã nội dòng: bọc mã bằng chuỗi backtick dài hơn, ví dụ ``code chứa ` bên trong`` sẽ thành <code>code chứa ` bên trong</code>. Với chính dấu gạch chéo ngược, hãy nhân đôi: \\. Hầu hết trình soạn thảo có xem trước Markdown sẽ cho bạn thấy ngay liệu thoát có hiệu lực, vì vậy hãy dùng xem trước khi nghi ngờ.

Callout của GitHub có chạy được trên công cụ khác không?

Cú pháp callout > [!NOTE] / [!TIP] / [!WARNING] / [!IMPORTANT] / [!CAUTION] được GitHub giới thiệu cuối năm 2023 và GitLab nhanh chóng theo sau. Các trình render chưa cài đặt (đa số trình tạo trang tĩnh, Notion và biên tập Markdown cũ) sẽ xử lý khối như một trích dẫn thông thường, khá đẹp - lời cảnh báo vẫn đọc đúng, chỉ thiếu băng màu. Nếu bạn đăng tài liệu lên nền tảng như MkDocs, Hugo, Jekyll, hãy ưu tiên cú pháp admonition gốc của nền tảng (ví dụ !!! note ... trong MkDocs Material). Để di động tối đa, viết callout dưới dạng trích dẫn in đậm tiền tố: > **Lưu ý:** ... sẽ render hợp lý ở mọi nơi.

Viết công thức toán trong Markdown thế nào?

Công thức nội dòng đặt giữa hai dấu đô-la đơn: $E = mc^2$. Công thức khối đặt giữa hai dấu đô-la kép trên dòng riêng, ví dụ $$\int_0^1 x^2 dx$$. Việc render phụ thuộc engine: GitHub, GitLab, Obsidian, Notion và Quarto hỗ trợ TeX/LaTeX qua KaTeX hoặc MathJax; CommonMark cổ điển thì không. Nếu xuất bản qua trình tạo trang tĩnh, hãy cài plugin toán (rehype-katex cho unified, mkdocs-material kèm arithmatex cho MkDocs, hugo-katex cho Hugo). Thoát dấu đô-la lẻ dùng làm tiền tệ bằng gạch chéo ngược: \$5, nếu không engine có thể vào chế độ toán và sinh kết quả lạ.

Làm sao tạo bảng trong Markdown và căn lề các cột?

Bảng dùng dấu gạch đứng để ngăn các cột và một dòng phân cách bằng dấu gạch ngang để tách tiêu đề khỏi phần thân: | Tên | Điểm | ở dòng đầu, |------|------| ở dòng hai, rồi mỗi bản ghi một dòng | giá trị | giá trị |. Các dấu gạch ngang chỉ cần có mặt, không cần căn theo chữ. Để điều khiển căn lề cột, thêm dấu hai chấm vào dòng phân cách: |:---| là trái, |:--:| là giữa, và |---:| là phải. Vậy một dòng như |:--|:-:|--:| cho các cột trái, giữa, phải. Bạn không cần dấu gạch đứng ở hai đầu, nhưng chúng giúp mã dễ đọc và sao chép hơn. Nếu một ô phải chứa ký tự gạch đứng thật, hãy thoát nó bằng gạch chéo ngược dạng \| để trình phân tích không coi đó là dấu ngăn cột; đây là lỗi phổ biến nhất khi đặt mã hay regex vào trong ô bảng. Bảng là tiện ích mở rộng GFM, nên GitHub, GitLab và Obsidian render được nhưng CommonMark thuần thì không.

Làm sao thêm dấu xuống dòng trong Markdown?

Markdown có ba cách buộc xuống dòng bên trong một đoạn. Cách cổ điển là kết thúc dòng bằng hai dấu cách rồi nhấn Enter; rắc rối là dấu cách cuối dòng vô hình và nhiều trình soạn thảo tự động xóa nó. Cách đáng tin hơn của GFM là một dấu gạch chéo ngược ở cuối dòng, nhìn thấy được trong mã nguồn và không bị mất khi cắt khoảng trắng. Cách thứ ba là thẻ HTML <br>, hoạt động trong gần như mọi trình render kể cả CommonMark thuần. Để bắt đầu một đoạn hoàn toàn mới thay vì ngắt mềm, chỉ cần để một dòng trống hoàn toàn giữa hai khối văn bản; đó là dấu phân tách di động nhất và là thứ bạn cần trong đa số trường hợp.

Tính năng Markdown nào chạy được trên GitHub, GitLab và CommonMark?

Tùy theo cấu trúc, và đó chính là điều mà huy hiệu tương thích trên mỗi thẻ thể hiện. In đậm, in nghiêng, tiêu đề, liên kết, hình ảnh, trích dẫn, danh sách và khối mã hàng rào là CommonMark cốt lõi, render giống nhau ở mọi nơi. Bảng, danh sách công việc, gạch ngang và liên kết URL trần là tiện ích GFM: GitHub, GitLab và Obsidian hỗ trợ, nhưng CommonMark thuần thì không. Chú thích cuối trang và công thức TeX/LaTeX render trên GitHub, GitLab và Obsidian nhưng không trên CommonMark thuần. Callout của GitHub (> [!NOTE]) chạy trên GitHub, GitLab và Obsidian (Obsidian có callout gốc) nhưng suy giảm thành trích dẫn thường ở nơi khác. @nhắc và tham chiếu #issue là riêng của GitHub. Danh sách định nghĩa (thuật ngữ / : định nghĩa) là tính năng của Markdown Extra / pandoc và không render trên cả bốn nền tảng. Với tài liệu phải sống sót qua mọi quy trình, hãy bật "Chỉ loại di động" để lọc bảng về tập con an toàn theo CommonMark.

Vì sao bảng tra cứu này tải nhanh hơn nhiều trang tài liệu khác?

Có ba lý do. Thứ nhất, mọi thẻ đều render sẵn ở máy chủ thành HTML tĩnh; không có parser Markdown phía khách phải chờ, không gói Mermaid, không JavaScript tô màu cú pháp - bytes bạn thấy chính là bytes máy chủ gửi. Thứ hai, tìm kiếm dùng bộ lọc querySelectorAll thuần trên vài chục thẻ, nên kể cả điện thoại đời thấp, mỗi lần gõ phím DOM cập nhật dưới một mili-giây. Thứ ba, trang được hạ tầng WuTools cache mạnh: HTML cache 10 ngày, JS lọc nhỏ cache một năm, biểu tượng SVG cũng vậy. Một khi khách quay lại đã có trang trong cache, bảng tra cứu hiện ra gần như đúng thời gian trình duyệt vẽ một khung hình.