Dấu đầu dòng cho danh sách không thứ tự#
Trong Markdown, để tạo danh sách không thứ tự, bạn thêm dấu gạch ngang (-), dấu sao (*), hoặc dấu cộng (+) trước mỗi mục. Thụt lề một hoặc nhiều mục để tạo danh sách lồng nhau:
- Mục A
- Mục B
- Mục lồng B.1* Mục A
* Mục B
* Mục lồng B.1Cả ba đều hiển thị giống hệt nhau. Chọn dấu nào là vấn đề phong cách — và đó chính xác là điều linter kiểm tra.
MD004 (ul-style)#
Quy tắc MD004 (ul-style) trong linter Markdown thực thi việc sử dụng nhất quán một ký tự làm dấu đầu dòng (bullet symbol) cho danh sách không thứ tự.
- Thẻ (Tags):
bullet,ul - Tên thay thế (Aliases):
ul-style - Khả năng tự động sửa (Fixable): Công cụ linter có thể tự động sửa một số vi phạm đơn giản.
- Tham số cấu hình (
style):consistent(mặc định): Cho phép dùng bất kỳ ký tự nào (*,-,+), nhưng toàn bộ danh sách trong tài liệu phải đồng nhất với kiểu của danh sách đầu tiên.asterisk: Bắt buộc dùng dấu sao (*).dash: Bắt buộc dùng dấu gạch ngang (-).plus: Bắt buộc dùng dấu cộng (+).sublist: Cho phép mỗi cấp danh sách lồng nhau (sublist) sử dụng một ký tự riêng biệt nhưng phải nhất quán theo cấp.
Cấu hình mặc định thường là “consistent”:
{
"ul-style": {
"style": "consistent"
}
}Ví dụ, khi bật kiểu sublist, tài liệu sau đây là hợp lệ vì cấp ngoài cùng dùng *, cấp thứ hai dùng +, và cấp trong cùng dùng -:
* Mục 1
+ Mục 2
- Mục 3
+ Mục 4
* Mục 5
+ Mục 6Vì sao tôi thích gạch ngang#
Mặc định có thể là dấu sao, nhưng tôi thấy gạch ngang (-) là kiểu phổ biến và dễ đọc nhất. Cũng có lý do thực tế: AI agent hầu như luôn viết gạch ngang, và chúng dùng dấu sao (**) rất nhiều cho chữ đậm. Bắt dấu sao làm đầu dòng vì vậy gây nhiễu — dấu * ở đầu dòng nhìn thoáng qua khó phân biệt giữa marker danh sách và định dạng đậm.
Đừng ép sửa tài liệu hiện có#
Đôi khi một tài liệu đã dùng dấu sao (*) xuyên suốt và hoàn toàn nhất quán. Tôi không muốn đụng vào tài liệu đó chỉ để thoả mãn một quy tắc. Linter không nên là lý do để viết lại nội dung sạch, nhất quán.
Lựa chọn 1: cấu hình kiểu gạch ngang#
Bạn có thể cập nhật cấu hình JSON (.markdownlint.json) để quy tắc chấp nhận gạch ngang:
{
"ul-style": {
"style": "dash"
}
}Lúc này gạch ngang vượt qua. Nhưng tài liệu chỉ dùng dấu sao vẫn lỗi, nên vấn đề sửa lại vẫn còn.
Lựa chọn 2: tắt quy tắc#
Quy tắc này ít giá trị — chọn dấu nào chỉ mang tính thẩm mỹ. Tôi thích tắt hẳn nó hơn:
{
"ul-style": false
}Giờ cả hai kiểu cùng tồn tại thoải mái. Mỗi tài liệu giữ quy ước riêng, không ép viết lại, và linter im lặng.
Kết luận#
Quy tắc phong cách là quan điểm, không phải lỗi. MD004 chỉ quan tâm bạn chọn dấu nào, mà tài liệu nào cũng tự chọn nhất quán một kiểu cả rồi. Cấu hình "dash" vẫn phạt các tài liệu dấu sao hiện có, nên tôi chọn "ul-style": false và để mỗi file giữ phong cách riêng.