Kiểm tra & sửa lỗi Markdown
Kiểm tra README, trang tài liệu hay bất kỳ file Markdown nào theo bộ quy tắc markdownlint: nhảy cấp tiêu đề, trộn ký hiệu gạch đầu dòng, dấu cách thừa cuối dòng, ký tự tab, thiếu dòng trống, URL trần, ảnh thiếu văn bản thay thế, liên kết #neo trỏ vào chỗ không có, bảng sai số ô và nhiều lỗi khác. Mỗi vấn đề hiện mã quy tắc, dòng và cột, và phần lớn lỗi khoảng trắng hay kiểu viết đều tự sửa được. Mọi thứ chạy ngay trên trình duyệt.
Các bước sử dụng
- Dán Markdown vào ô Markdown, hoặc dùng thanh nhập liệu ở đầu ô: Mở file, Dán, Dữ liệu mẫu (Ví dụ của công cụ này, README, Tài liệu API có bảng & code, Biên bản họp, Bài blog) và Xoá. Bạn cũng có thể kéo thả file
.mdvào ô. - Chọn Bộ quy tắc: Mặc định của markdownlint bật mọi quy tắc với thiết lập mặc định của markdownlint, Nới lỏng (tài liệu) tắt giới hạn độ dài dòng, yêu cầu tiêu đề ở dòng đầu và lỗi dùng chữ nhấn mạnh làm tiêu đề, đồng thời cho phép các thẻ HTML hay dùng như
<details>,<kbd>, còn Nghiêm ngặt cố định thêm kiểu tiêu đề, danh sách, nhấn mạnh, khối code và dấu|của bảng. - Mở khung quy tắc để bật/tắt từng quy tắc và chỉnh tuỳ chọn, ví dụ
line_lengthcủa MD013 hayallowed_elementscủa MD033. Khi bạn thay đổi bất cứ gì, bộ quy tắc chuyển thành Tuỳ chỉnh. Quy tắc gắn nhãn Tự sửa được có thể sửa tự động. - Đã có sẵn cấu hình? Dùng Nhập .markdownlint.json. Xuất .markdownlint.json lưu thiết lập hiện tại để đặt vào kho mã, còn Sao chép cấu hình chép đúng nội dung JSON đó vào clipboard.
- Xem thẻ Vấn đề. Lọc theo Tất cả, Lỗi hoặc Cảnh báo, hoặc chọn một quy tắc thay cho Mọi quy tắc. Bấm vào một vấn đề để chọn đúng dòng đó trong ô nhập.
- Mở Tự sửa để xem trước tài liệu đã sửa dưới dạng danh sách các dòng thay đổi. Sau đó bấm Sao chép Markdown đã sửa, Tải .md hoặc Thay ô nhập bằng bản đã sửa.
- Tổng hợp đếm số vấn đề theo từng quy tắc. Xuất kết quả bằng Sao chép báo cáo, Báo cáo JSON hoặc Báo cáo Markdown.
Mẹo
- Chú thích nội dòng hoạt động giống markdownlint:
<!-- markdownlint-disable MD013 -->và<!-- markdownlint-enable MD013 -->bao quanh một đoạn,<!-- markdownlint-disable-next-line MD033 -->đặt phía trên một dòng,<!-- markdownlint-disable-line -->ở cuối dòng, và<!-- markdownlint-disable-file -->cho cả file. Có thể dùng cả tên gọi khác nhưline-lengthhay nhóm nhưwhitespace. - Không báo lỗi bên trong khối code rào (
```/~~~), khối code thụt lề hay YAML/TOML front matter. Ngoại lệ duy nhất là các quy tắc về chính khối code: thiếu ngôn ngữ (MD040), trộn kiểu khối code (MD046), dòng trống quanh khối rào (MD031) và, nếu bạn để bật, độ dài dòng trong code (MD013). - MD051 tạo neo tiêu đề giống GitHub, nên tiêu đề "FAQ" thứ hai có neo
#faq-1. Liên kết tới neoid="…"trong HTML cũng được tính. - Dấu cách cuối dòng được giữ khi nó tạo ngắt dòng thật: với
br_spacesbằng 2, đúng hai dấu cách trước một dòng tiếp theo là hợp lệ, và khi sửa, chuỗi dài hơn được cắt về hai. - Tab ở đầu dòng được thay bằng dấu cách tới mốc 4 cột kế tiếp, nên danh sách lồng nhau vẫn giữ nguyên cấp sau khi sửa.
Câu hỏi thường gặp
Công cụ này có giống markdownlint không?
Công cụ dùng đúng mã quy tắc, tên gọi khác, tên tuỳ chọn và định dạng .markdownlint.json của markdownlint, nên cấu hình xuất ở đây dùng được với markdownlint-cli2 hay tiện ích VS Code và ngược lại. Tuy vậy, đây là bản cài đặt riêng chứ không phải chính thư viện markdownlint. Nó có 37 quy tắc hữu ích nhất, và vài trường hợp đặc biệt có thể báo hơi khác. Những thiết lập không nhận ra sẽ được liệt kê là bị bỏ qua khi bạn nhập file.
Những lỗi nào sửa tự động được?
Dấu cách thừa cuối dòng, ký tự tab, dòng trống thừa, thiếu dòng trống quanh tiêu đề, khối code rào và danh sách, dấu cách sau #, kiểu ký hiệu gạch đầu dòng, số thứ tự danh sách, kiểu in nghiêng và in đậm, URL trần (bọc thành <url>) và ký tự xuống dòng cuối file. Mọi quy tắc làm được việc này đều gắn nhãn Tự sửa được.
Tài liệu của tôi có bị tải lên không?
Không. Việc kiểm tra, sửa và xuất báo cáo đều chạy ngay trên trình duyệt của bạn, không có gì được gửi lên máy chủ.