Thụt lề Markdown: danh sách lồng nhau, đoạn văn và mã
Sửa thụt lề Markdown qua ví dụ về danh sách dấu đầu dòng lồng nhau, danh sách đánh số, đoạn văn tiếp nối và mã có hàng rào. Tránh vô tình tạo khối mã.
Để thụt lề một danh sách con Markdown, hãy căn ký hiệu của nó bên dưới ký tự đầu tiên trong văn bản của mục cha. Với - Mục cha, cần hai dấu cách. Với 1. Mục cha, cần ba dấu cách. Thụt lề điều khiển cấu trúc tài liệu, nên thêm dấu cách vào đoạn văn thông thường có thể tạo hiệu ứng rất khác so với thay đổi thụt lề trực quan của đoạn văn trong Word.
Bắt đầu với ví dụ này trong trình xem Markdown:
- Tài liệu dự án
- Hướng dẫn cài đặt
- Ghi chú phát hành
- Danh sách kiểm tra khi duyệt
Hướng dẫn cài đặt và ghi chú phát hành phải xuất hiện bên dưới mục tài liệu dự án. Danh sách kiểm tra khi duyệt phải giữ ở cấp bên ngoài.
Đếm từ vị trí nội dung của mục cha
Với mục danh sách thông thường được viết bằng một dấu cách sau ký hiệu, hãy dùng hướng dẫn căn lề sau:
| Mục cha bắt đầu bằng | Số ký tự trước văn bản | Thụt lề danh sách con |
|---|---|---|
- | 2 | 2 dấu cách |
1. | 3 | 3 dấu cách |
12. | 4 | 4 dấu cách |
100. | 5 | 5 dấu cách |
Đây là lý do một quy tắc chung như "luôn dùng hai dấu cách" không phù hợp với danh sách đánh số. Tài liệu về danh sách lồng nhau của GitHub minh họa cách căn theo nội dung mục cha, kể cả với ký hiệu số dài hơn.
1. Chuẩn bị bản phát hành
- Xác nhận số phiên bản.
- Cập nhật nhật ký thay đổi.
2. Xuất bản tài liệu
Các ký hiệu lồng nhau có ba dấu cách ở đầu. Nếu bắt đầu ở lề trái, chúng tạo một danh sách riêng thay vì thuộc bước đánh số đầu tiên.
Khi làm việc với một bộ xử lý Markdown cũ, hãy xem trước tệp bằng chính bộ xử lý đó. Các ví dụ ở đây hướng đến phân tích theo kiểu CommonMark và GitHub Markdown; những triển khai cũ có thể nhận diện khối lồng nhau theo cách khác.
Thêm đoạn văn trong một mục danh sách
Một phần giải thích dài hơn không cần dấu đầu dòng riêng. Chừa một dòng trống, sau đó căn đoạn văn mới bên dưới văn bản của mục:
1. Duyệt hướng dẫn cài đặt.
Xác nhận rằng người đọc mới có thể hoàn tất thiết lập mà không
cần mở tài liệu nội bộ.
2. Phê duyệt ghi chú phát hành.
Đoạn giải thích thuộc bước một. Hai dòng nguồn của nó được hiển thị liền nhau, trừ khi bạn thêm ngắt dòng tường minh.
Bỏ ba dấu cách có thể kết thúc danh sách đánh số và biến lời giải thích thành đoạn văn thông thường. Điều đó cũng có thể làm danh sách tiếp theo bắt đầu đánh số lại trong một số quy trình chỉnh sửa.
Mẫu tương tự cũng dùng được với danh sách dấu đầu dòng:
- Hướng dẫn cài đặt
Bao gồm điều kiện tiên quyết, lệnh thiết lập và một bước xác minh.
- Ghi chú phát hành
Dùng đoạn văn riêng khi phần giải thích chứa nhiều câu. Dùng danh sách con khi có các mục riêng biệt mà người đọc cần xem lần lượt.
Đặt mã bên trong một bước đánh số
Mã có hàng rào làm rõ ranh giới của ví dụ lệnh. Thụt lề hàng rào mở, nội dung và hàng rào đóng để giữ khối bên trong mục danh sách:
1. Kiểm tra phiên bản đã cài đặt.
```sh
node --version
```
Ghi lại kết quả trong ghi chú duyệt.
2. Chạy các kiểm tra của dự án.
Ở đây, hàng rào bắt đầu bên dưới chữ đầu tiên của Kiểm tra. Đoạn văn sau hàng rào dùng cùng cách căn lề, nên cũng nằm trong bước đầu tiên.
Nếu bước đánh số tiếp theo trở thành một phần của khối mã, hãy kiểm tra hàng rào đóng. Nếu mã xuất hiện bên ngoài danh sách, hãy kiểm tra các dấu cách trước hàng rào. Xem hướng dẫn khối mã để tìm hiểu nhãn ngôn ngữ và cách hiển thị dấu nháy ngược theo nghĩa đen.
Vì sao bốn dấu cách có thể biến văn bản thành mã
Ở cấp ngoài cùng của tài liệu, sau một dòng trống, bốn dấu cách trước một dòng có thể tạo khối mã thụt lề:
Một đoạn văn thông thường.
Dòng này được hiển thị dưới dạng mã.
Đây là cú pháp Markdown có chủ đích, không phải chức năng thụt lề bị hỏng. Tài liệu tham khảo khối mã thụt lề CommonMark giải thích vai trò của thụt lề và ranh giới khối.
Một dòng thụt lề ngay sau văn bản đoạn văn thông thường có những ràng buộc phân tích khác, nên chèn dấu cách không phải cách đáng tin cậy để tạo thụt lề trực quan cho đoạn văn. Trong danh sách, số dấu cách cần thiết còn được tính tương đối theo mục chứa nó.
Với phần trích dẫn, hãy dùng khối trích dẫn. Với văn xuôi thông thường cần thụt dòng đầu trong báo cáo cuối cùng, hãy giữ Markdown là đoạn văn bình thường rồi áp dụng định dạng đoạn văn trong Word sau khi xuất. Những lựa chọn đó bảo toàn ý nghĩa dự kiến của nội dung.
Ưu tiên dấu cách khi tìm lỗi
Tab có thể chiếm nhiều cột hiển thị, và các trình soạn thảo khác nhau có thể hiển thị chúng với chiều rộng khác nhau. Nếu danh sách trông thẳng hàng trong mã nguồn nhưng kết xuất sai, hãy bật hiển thị khoảng trắng trong trình soạn thảo và thay tab đầu dòng bằng số dấu cách cần thiết.
Đừng thay tab trong các ví dụ mã một cách bừa bãi. Ở đó, khoảng trắng có thể là một phần của chính ví dụ. Chỉ dọn các ký hiệu Markdown và thụt lề của phần tiếp nối quyết định cấu trúc danh sách xung quanh.
Tránh dùng lặp lại thực thể khoảng trắng không ngắt dòng để giả lập danh sách lồng nhau. Điều này có thể khiến văn bản trông bị dịch sang bên trong một bản xem trước, trong khi tài liệu bên dưới vẫn là các đoạn văn không liên quan.
Xác minh cấu trúc trước khi xuất Word
Kiểm tra một phần tiêu biểu chứa mục cha, danh sách con, đoạn văn thứ hai và khối mã có hàng rào. Trong trình chuyển đổi Markdown sang HTML, một danh sách lồng nhau thực sự nằm bên trong mục danh sách cha; chỉ dịch vị trí hiển thị không tạo ra quan hệ đó.
Sau đó dùng trình chuyển đổi Markdown sang Word và mở DOCX. Kiểm tra xem số thứ tự có tiếp tục đúng dự kiến và các lệnh có còn gắn với bước tương ứng hay không. Kiểu danh sách của Word có thể dùng khoảng cách hiển thị khác trình duyệt, vì vậy hãy đánh giá cả hệ thống phân cấp và diện mạo tài liệu cuối cùng trước khi chia sẻ.