Làm chủ Markdown List: Tiêu chuẩn thụt lề CommonMark & GitHub Flavored Markdown (GFM)
Nền tảng kỹ thuật của việc hiển thị Markdown List
Markdown đã khẳng định vị thế là ngôn ngữ đánh dấu tiêu chuẩn cho tài liệu phần mềm hiện đại, tài liệu kỹ thuật, cơ sở dữ liệu trí thức cá nhân và giao tiếp giữa các nhà phát triển. Mặc dù các danh sách đầu dòng đơn cấp (- item) và danh sách đánh số (1. item) trông rất đơn giản, việc xây dựng các dàn ý tài liệu phân cấp lồng nhau phức tạp lại phát sinh nhiều vấn đề định dạng. Các trình phân tích Markdown khác nhau—như CommonMark, GitHub Flavored Markdown (GFM), Python-Markdown và Pandoc—áp dụng các quy tắc nghiêm ngặt về việc chọn ký tự đầu dòng, tỷ lệ tab/khoảng trắng và độ thụt lề của các khối con.
Khi danh sách được dán qua lại giữa các trình chỉnh sửa văn bản khác nhau (như VS Code, Sublime Text, Xcode, Apple Notes hoặc Microsoft Word), các lỗi thụt lề ẩn sẽ xuất hiện. Chỉ cần thiếu một khoảng trắng ở mục con, trình biên dịch Markdown sẽ hiểu sai nút con lồng nhau đó thành một mục cấp cao nhất hoặc một đoạn văn độc lập. Công cụ Nested List & Indentation Formatter của Utiliome loại bỏ các lỗi này bằng cách phân tích cây cú pháp AST (Abstract Syntax Tree) của văn bản đầu vào và tái tạo lại mã Markdown chuẩn xác.
Quy tắc thụt lề: 2 khoảng trắng vs 4 khoảng trắng
Một trong những tranh luận phổ biến nhất trong thiết kế tài liệu kỹ thuật là nên thụt lề danh sách con bằng 2 hay 4 khoảng trắng cho mỗi cấp phân cấp. Lựa chọn phụ thuộc vào quy chuẩn trình phân tích Markdown mục tiêu:
Quy tắc thụt lề 2 khoảng trắng (Chuẩn GFM & Prettier): Trong hệ sinh thái tài liệu web hiện đại như GitHub, Docusaurus, Nextra và Obsidian, 2 khoảng trắng cho mỗi cấp thụt lề là tiêu chuẩn được công nhận. Quy tắc 2 khoảng trắng căn chỉnh nội dung con ngay dưới điểm bắt đầu văn bản của mục cha:
- Mục cấp cao nhất 1 - Mục con lồng nhau 1.1 - Mục con lồng nhau 1.2 - Mục cháu lồng sâu 1.2.1 - Mục cấp cao nhất 2Quy tắc thụt lề 4 khoảng trắng (Chuẩn CommonMark nghiêm ngặt & Python-Markdown): Các trình triển khai CommonMark nghiêm ngặt yêu cầu các khối con, đoạn mã và danh sách lồng bên trong danh sách đánh số phải được thụt lề 4 khoảng trắng (hoặc 1 phím Tab) để đảm bảo tính chứa đựng đúng đắn của khối cha:
1. Bước đánh số đầu tiên trong quy trình - Mục đầu dòng con A liên quan - Mục đầu dòng con B liên quan 2. Bước đánh số thứ hai trong quy trìnhBẫy lẫn lộn giữa Tab và Space: Việc trộn lẫn ký tự Tab (
\t) với ký tự khoảng trắng ASCII (\x20) là nguyên nhân hàng đầu gây ra lỗi hiển thị tài liệu Markdown. Các trình duyệt hiển thị tab không đồng nhất (thường là 4 hoặc 8 cột), khiến các mục lồng nhau bị lệch về mặt thị giác. Utiliome tự động chuyển đổi tất cả ký tự tab thành chuỗi khoảng trắng đồng nhất theo cấu hình tùy chọn của bạn.
Chuẩn hóa ký tự đầu dòng & Sửa thứ tự đánh số
Markdown hỗ trợ ba ký tự đầu dòng khác nhau cho danh sách không phân cấp: dấu gạch ngang (-), dấu sao (*) và dấu cộng (+). Mặc dù cả ba đều tạo ra các phần tử HTML danh sách (<ul>) hợp lệ, việc dùng lẫn lộn các ký tự trong cùng một tài liệu gây rối mắt và không vượt qua được các công cụ kiểm tra lỗi tự động (như quy tắc markdownlint MD004).
Hơn nữa, thứ tự đánh số danh sách thường bị lỗi trong quá trình chỉnh sửa. Người dùng thường dán các mục vào giữa chuỗi số hoặc phụ thuộc vào cú pháp tự tăng 1.:
<!-- Đầu vào chưa định dạng / Lỗi -->
* Tính năng A
- Tính năng B
+ Tính năng C
1. Bước khởi đầu
1. Bước thứ hai (sao chép từ bản thảo)
4. Bước sai thứ tự
Công cụ của Utiliome sẽ chuẩn hóa tất cả các ký tự đầu dòng về một ký tự thống nhất do bạn chọn (ví dụ: đổi tất cả thành -) và đánh lại số thứ tự một cách tuyến tính (1., 2., 3.) hoặc chuẩn hóa về mức tăng một chữ số (1., 1., 1.) tùy theo quy định của đội ngũ bạn.