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ạ.

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.