Markdown được cho phép.Tài liệu có lỗi cấu trúc vẫn có thể hiển thị, điều này khiến những lỗi đó dễ bị bỏ sót cho đến khi bảng bị hỏng, tiêu đề biến mất khỏi điều hướng hoặc hình ảnh trở nên vô nghĩa đối với người dùng trình đọc màn hình.
Markdown linting là quá trình kiểm tra văn bản nguồn để tìm các vấn đề về cấu trúc, khả năng truy cập và tính nhất quán trước khi xuất bản.Bắt đầu với Trình kiểm tra Markdown để phát hiện các cấp tiêu đề bị bỏ qua, văn bản thay thế hình ảnh bị thiếu, URL trống, hàng rào mã không được gắn nhãn hoặc không được đóng và khoảng trắng ở cuối.Sau đó, hãy sử dụng danh sách kiểm tra thủ công trong hướng dẫn này để xem xét biên tập rộng hơn.
Linting không phải là việc thực thi các tùy chọn tùy ý.Một quy tắc hữu ích sẽ ngăn chặn vấn đề thực sự về đọc, hiển thị, bảo trì hoặc khả năng truy cập.
Danh sách kiểm tra trước khi xuất bản nhanh
| Kiểm tra | Tại sao nó quan trọng | Tự động hay thủ công? |
|---|---|---|
| Phân cấp tiêu đề | Bảo toàn cấu trúc tài liệu | Kẻ nói dối |
| Văn bản thay thế hình ảnh | Làm cho hình ảnh có thể hiểu được mà không cần nhìn | Kẻ nói dối |
| Liên kết mô tả | Cải thiện khả năng truy cập và quét | Linter + xem xét thủ công |
| Hàng rào mã đóng | Ngăn phần còn lại của trang trở thành mã | Kẻ nói dối |
| Nhãn ngôn ngữ mã | Cho phép đánh dấu cú pháp hữu ích | Kẻ nói dối |
| Khoảng trắng ở cuối | Tránh hành vi vô hình, cụ thể theo phương ngữ | Kẻ nói dối |
| Một tiêu đề trang rõ ràng | Giữ mục đích trang rõ ràng | Xem xét thủ công |
| Danh sách nhất quán | Ngăn chặn sự lồng ghép bị hỏng | Xem xét thủ công |
| Bảng hợp lệ | Giữ nguyên cấu trúc cột | Xem xét thủ công |
| Tiêu đề duy nhất | Ngăn chặn sự nhầm lẫn về neo trùng lặp | Xem xét thủ công |
| Cách sử dụng HTML di động | Tránh các lỗi cụ thể của trình kết xuất | Xem xét thủ công |
| Đoạn văn có thể đọc được | Cải thiện khả năng hiểu | Xem xét thủ công |
Dán tài liệu đại diện vào kẻ nói dối, chạy kiểm tra, sửa các dòng được báo cáo và sau đó xem trước trang hoàn chỉnh trong hệ thống xuất bản thực tế của nó.
1. Cấp độ tiêu đề bị bỏ qua
Sự cố
# Deployment Guide
### Configure credentials
Tài liệu chuyển từ H1 sang H3.Nó có thể trông chấp nhận được khi kích thước phông chữ là tín hiệu hiển thị duy nhất, nhưng đường viền cấu trúc thiếu một mức độ.
Sửa
# Deployment Guide
## Configure credentials
Sử dụng tiêu đề để mô tả thứ bậc chứ không phải để chọn kích thước trực quan.Nếu “Định cấu hình thông tin đăng nhập” thực sự thuộc về một phần bị thiếu, hãy thêm phần đó:
# Deployment Guide
## Preparation
### Configure credentials
Các Trình kiểm tra Markdown báo cáo tiêu đề tăng nhiều hơn một cấp.
2. Nhiều hoặc thiếu tiêu đề H1
Một trang thường có một tiêu đề rõ ràng.Một số hệ thống tài liệu tạo ra H1 từ vật chất phía trước, trong khi những hệ thống khác mong đợi nó ở phần thân Markdown.Biết quy ước nào trang web của bạn sử dụng.
Nguồn không rõ ràng
# Installation
# Configuration
Xóa nguồn
# Product setup
## Installation
## Configuration
Nếu mẫu trang web của bạn hiển thị title: Product setup là trang H1, thay vào đó, nội dung có thể bắt đầu bằng H2.Quy tắc không phải là “mỗi tệp Markdown phải chứa chính xác một tệp #.” The rule is “the rendered page needs one unambiguous primary heading.”
3. Tiêu đề chỉ dùng để nhấn mạnh
Nguồn này tạo ra một mục nhập phác thảo không cần thiết:
#### Important!
Nếu văn bản không giới thiệu một phần, hãy sử dụng văn xuôi hoặc chú thích thích hợp:
**Important:** Back up the database before continuing.
Tiêu đề sẽ giúp người đọc điều hướng.Các tiêu đề trang trí làm cho mục lục trở nên ồn ào và làm giảm tính hữu ích của việc điều hướng hỗ trợ.
4. Hình ảnh không có văn bản thay thế
Sự cố

Hình ảnh không có văn bản thay thế.Người đọc không thể nhìn thấy nó sẽ không nhận được lời giải thích và ai đó duyệt các hình ảnh bị hỏng hoặc bị vô hiệu hóa sẽ không thể xác định được mục đích của nó.
Sửa

Mô tả thông tin mà hình ảnh đóng góp chứ không chỉ hình thức bên ngoài của nó.Tránh các cụm từ như “hình ảnh của” trừ khi phương tiện truyền đạt quan trọng.
Hình ảnh trang trí là trường hợp đặc biệt.Văn bản thay thế trống có thể chính xác trong HTML khi hình ảnh không truyền tải thông tin nào nhưng trình kết xuất Markdown và quy trình làm việc nội dung lại khác nhau.Nếu một hình ảnh chỉ mang tính chất trang trí, trước tiên hãy hỏi xem nó có thuộc tài liệu kỹ thuật nào không.
Cờ nói dối gắn cờ hình ảnh Markdown với văn bản thay thế trống.các Trình định dạng hình ảnh có thể tạo đánh dấu hình ảnh với chú thích tùy chọn và thay thế rõ ràng.
5. Liên kết yếu hoặc đơn giản
Sự cố
Visit https://example.com/docs/setup for more information.
URL trống khó quét và có thể gây khó chịu khi đọc to.Văn bản liên kết chung cũng không tốt hơn nhiều:
[Click here](https://example.com/docs/setup).
Sửa
Read the [service setup guide](https://example.com/docs/setup).
Liên kết mô tả cho người đọc biết họ sẽ mở những gì.Chúng cũng vẫn có ý nghĩa khi được trích xuất thành danh sách các liên kết.
Kẻ nói dối xác định nhiều trần http:// and https:// URL, nhưng vẫn cần phải xem xét biên tập để đánh giá liệu văn bản liên kết có hữu ích hay không.
6. Hàng rào mã không được đóng
Sự cố
```javascript
const status = 'ready';
## Next section
Nếu không có hàng rào đóng, trình kết xuất có thể coi phần còn lại của trang là mã.
Sửa
```javascript
const status = 'ready';
```
## Next section
Hàng rào không kín có thể phá vỡ một phần lớn của một tài liệu hợp lệ.Kẻ nói dối báo cáo đường nơi hàng rào chưa từng có bắt đầu.
7. Hàng rào mã không có mã định danh ngôn ngữ
Ít hữu ích hơn
```
npm run build
```
Tốt hơn
```bash
npm run build
```
Mã nhận dạng ngôn ngữ cho phép đánh dấu cú pháp và truyền đạt loại nội dung mà người đọc đang xem.Sử dụng các định danh phổ biến như javascript, typescript, json, html, css, bash, powershell, yamlhoặc markdown.
Không thêm ngôn ngữ không chính xác chỉ để lấy màu sắc.Đối với đầu ra không có cấu trúc, sử dụng text khi đích nhận ra nó.
8. Thụt lề danh sách không nhất quán
Sự cố
- Install dependencies
- Production packages
* Development packages
- Optional tools
Các tab, dấu cách và điểm đánh dấu hỗn hợp rất khó xem xét và có thể hiển thị ở các cấp độ khác nhau.
Sửa
- Install dependencies
- Production packages
- Development packages
- Optional tools
Chọn chiều rộng thụt đầu dòng nhất quán cho dự án.Số lượng khoảng trắng chính xác có thể phụ thuộc vào phương ngữ Markdown và nội dung danh sách, nhưng tính nhất quán là điều cần thiết.
Sử dụng Trình định dạng danh sách lồng nhau để chuẩn hóa các dấu đầu dòng, đánh số, tab và thụt lề hỗn hợp trước khi xem xét lần cuối.
9. Chuỗi số được nhập thủ công
Danh sách được đánh số dài rất tốn kém để duy trì:
1. Download the package.
2. Verify the checksum.
3. Install the package.
4. Restart the service.
Nhiều trình kết xuất Markdown cho phép mọi mục sử dụng 1. trong khi vẫn hiển thị trình tự có thứ tự:
1. Download the package.
1. Verify the checksum.
1. Install the package.
1. Restart the service.
Điều này làm giảm tiếng ồn khi đánh số lại trong các khác biệt nguồn.Tuy nhiên, nguồn được đánh số rõ ràng sẽ dễ thảo luận hơn khi hướng dẫn tham khảo “bước 3”.Chọn một quy ước dự án và áp dụng nó một cách nhất quán.
Không kết hợp các số đã nhập, dấu danh sách theo thứ tự và văn bản đoạn văn.Xác nhận kết quả được hiển thị sau khi chỉnh sửa các bước lồng nhau.
10. Bảng không đúng định dạng
Sự cố
| Name | Status | Owner |
| --- | --- |
| Search | Ready | Maya |
| Billing | Review |
Dấu phân cách và hàng dữ liệu không chứa cùng số cột logic.
Sửa
| Name | Status | Owner |
| --- | --- | --- |
| Search | Ready | Maya |
| Billing | Review | Unassigned |
Đồng thời kiểm tra các ký tự ống không thoát bên trong các ô:
| Command | Description |
| --- | --- |
| `test \| deploy` | Run the matching stage |
Các Trình định dạng bảng Markdown giúp hiển thị các hàng không đồng đều và tạo ra nguồn căn chỉnh.Để tạo một bảng mới một cách trực quan, hãy sử dụng Markdown Generator bảng.
11. Tiêu đề trùng lặp và va chạm neo
Một tài liệu có thể lặp lại một cách hợp pháp một tiêu đề hiển thị chẳng hạn như “Ví dụ”, nhưng ID neo được tạo tự động có thể trở thành #examples, #examples-1và #examples-2.Quy tắc chính xác thay đổi tùy theo trình kết xuất.
Các tiêu đề lặp đi lặp lại làm cho các liên kết thủ công trở nên dễ vỡ:
- [API examples](#examples)
- [CLI examples](#examples)
Thích tiêu đề mô tả hơn:
## API examples
## CLI examples
Sau đó tạo một mục lục với Markdown Máy phát điện TOC và xác minh các điểm neo trong nền tảng đích.
12. Khoảng trắng ở cuối
Dấu cách ở cuối dòng là vô hình.Trong một số phương ngữ Markdown, hai dấu cách ở cuối tạo ra dấu ngắt dòng cứng, nghĩa là một hành động vô tình của người chỉnh sửa có thể thay đổi kết xuất.
Kẻ nói dối báo cáo khoảng trắng ở cuối để bạn có thể quyết định xem đó có phải là cố ý hay không.Thích một dòng trống để phân tách đoạn văn.Nếu thực sự cần phải ngắt dòng cứng, hãy ghi lại và áp dụng nhất quán quy ước đã chọn của dự án.
Người chỉnh sửa thường có thể tự động xóa khoảng trắng ở cuối khi lưu, nhưng hãy kiểm tra xem điều này có thay đổi việc ngắt dòng có chủ ý trong nội dung cũ hay không.
13. Nguyên HTML Làm Giảm Tính Di Động
Markdown thường cho phép nhúng HTML:
<div class="warning-panel">
Restarting the service ends active sessions.
</div>
Khối đó có thể hoạt động trên một trang web và bị thoát, loại bỏ hoặc tạo kiểu không chính xác ở nơi khác.Thích Markdown di động hơn khi nó có thể diễn đạt ý nghĩa tương tự:
> **Warning:** Restarting the service ends active sessions.
Sử dụng HTML có chủ ý cho các tính năng Markdown không thể biểu thị, chẳng hạn như định cỡ hình ảnh được kiểm soát hoặc một tính năng được hỗ trợ <details> .Giữ một danh sách các đích đến mà nội dung phải hiển thị và kiểm tra từng đích đến.
Các Trình tạo chú thích có thể tạo cú pháp dành riêng cho nền tảng cho GitHub, Obsidian và MkDocs khi tính di động ít quan trọng hơn bản trình bày gốc.
14. Đoạn văn quá dài và khả năng quét kém
Markdown có thể hợp lệ về mặt cấu trúc nhưng vẫn khó đọc.Một bức tường văn bản chứa nhiều quyết định, cảnh báo và thủ tục cần được sắp xếp lại.
Sử dụng:
- đoạn văn ngắn cho một ý chính;
- tiêu đề mô tả để điều hướng;
- danh sách các mục song song;
- cho các trường có thể so sánh thực sự;
- khối mã cho đầu vào và đầu ra theo nghĩa đen;
- chú thích cho một số ít trường hợp ngoại lệ quan trọng.
Đừng biến mọi câu thành một viên đạn.Danh sách hoạt động tốt nhất khi các mục có cùng vai trò ngữ pháp và khái niệm.
Sử dụng Đếm từ và thời gian đọc để kiểm tra số lượng đoạn văn, số lượng tiêu đề và độ dài đọc nhưng coi số liệu thống kê là tín hiệu chứ không phải là mục tiêu.
15. Cú pháp dành riêng cho trình kết xuất không có kế hoạch tương thích
GitHub danh sách nhiệm vụ, liên kết Obsidian wiki, MkDocs lời khuyên, chú thích cuối trang, danh sách định nghĩa và nội dung chính đều hữu ích nhưng chúng không được hỗ trợ giống nhau ở mọi nơi.
Ví dụ:
> [!NOTE]
> This callout is useful in destinations that recognize the syntax.
Trước khi áp dụng tiện ích mở rộng, hãy trả lời ba câu hỏi:
- Trình kết xuất nào sở hữu đầu ra cuối cùng?
- Sau này nội dung có cần chuyển đi nơi khác không?
- Người đọc sẽ thấy gì khi tiện ích mở rộng không được hỗ trợ?
Giữ nền tảng Markdown di động và thêm cú pháp nền tảng ở cạnh xuất bản khi có thể.
Quy trình Linting thực tế
Bước 1: Kiểm tra cấu trúc
Dán nguồn vào Trình kiểm tra Markdown.Đầu tiên hãy sửa lỗi, sau đó là cảnh báo, sau đó là các mục thống nhất về thông tin.Kiểm tra tự động sẽ xác định vị trí;họ không nên âm thầm viết lại ý nghĩa.
Bước 2: Chuẩn hóa các phần tử khó
Sử dụng các công cụ tập trung để dọn dẹp cơ học:
- Trình định dạng danh sách lồng nhau để thụt lề;
- Trình định dạng bảng Markdown cho bàn ống;
- Trình định dạng hình ảnh để đánh dấu hình ảnh;
- Trình tạo mục lục cho các neo tiêu đề.
Các thay đổi tập trung tạo ra những khác biệt nhỏ hơn, dễ xem xét hơn so với một trình định dạng rộng viết lại toàn bộ tệp.
Bước 3: Xem trước tài liệu
Mở nguồn trong Markdown Trình soạn thảo và so sánh Markdown với kết quả được hiển thị.Kiểm tra:
- tiêu đề và mục lục;
- danh sách và danh sách nhiệm vụ;
- bảng trên màn hình hẹp;
- hình ảnh và liên kết;
- khối mã và mã nội tuyến;
- chú thích hoặc chú thích thô HTML.
Bước 4: Kiểm tra đích thực
Bản xem trước chung không thể sao chép mọi trình kết xuất.Mở tệp trong GitHub, Obsidian, GitLab, MkDocs hoặc trang tài liệu thực tế trước khi xuất bản.
Bước 5: Xem lại ý nghĩa, không chỉ cú pháp
Không kẻ nói dối nào có thể xác định liệu một quy trình có an toàn hay không, một liên kết trỏ đến chính sách dự định hoặc một mô tả hình ảnh truyền đạt kết luận quan trọng.Người đánh giá phải xác nhận tính chính xác, đầy đủ, giọng điệu và sự phù hợp với khán giả.
Đề xuất Hướng dẫn về Phong cách Nhóm
Một quy ước ngắn gọn được ghi thành văn bản sẽ hiệu quả hơn hàng tá sở thích ngầm.Xác định:
- tiêu đề trang nằm ở phần đầu hay phần nội dung Markdown;
- tiến trình tiêu đề được phép;
- thụt lề danh sách và kiểu danh sách có thứ tự;
- yêu cầu về ngôn ngữ hàng rào mã;
- cách xem xét hình ảnh và văn bản thay thế;
- giới hạn độ phức tạp của bảng;
- cho phép HTML và các tiện ích mở rộng nền tảng;
- độ dài dòng tối đa, nếu đội sử dụng một dòng;
- cách kiểm tra các liên kết;
- quy tắc kẻ nói dối chặn xuất bản.
Bắt đầu với các quy tắc ngăn ngừa lỗi thực sự.Chỉ thêm quy tắc khi nhóm hiểu được vấn đề mà nó giải quyết được.
FAQ
Markdown có thể truy cập tự động được không?
Không. Cú pháp hợp lệ vẫn có thể chứa văn bản thay thế trống, liên kết mơ hồ, tiêu đề khó hiểu, sơ đồ không thể truy cập và thứ tự đọc kém.Khả năng tiếp cận yêu cầu xem xét cấu trúc và biên tập.
Liệu Markdown Linter có viết lại tài liệu của tôi không?
Kẻ nói dối WordToMD báo cáo các vấn đề về đánh số dòng.Nó không âm thầm viết lại nguồn, vì vậy bạn giữ quyền kiểm soát mỗi lần sửa.
Tại sao kẻ nói dối lại báo cáo một URL trống?
Văn bản liên kết mô tả dễ quét hơn và hữu ích hơn cho công nghệ hỗ trợ.Thay thế URL bằng nhãn có ý nghĩa trừ khi địa chỉ bằng chữ là thông tin mà người đọc cần.
Hàng rào mã không được gắn nhãn có phải luôn sai không?
Không phải lúc nào cũng vậy, nhưng mã định danh ngôn ngữ chính xác thường cải thiện độ rõ ràng và làm nổi bật cú pháp.sử dụng text cho đầu ra đơn giản khi được hỗ trợ thay vì chỉ định ngôn ngữ lập trình không chính xác.
Tất cả các dự án có nên sử dụng cùng một quy tắc linting không?
Không. Một GitHub README, một Obsidian vault, một tham chiếu API và một trang xuất bản có các quy ước khác nhau.Chia sẻ bộ quy tắc cốt lõi về cấu trúc và khả năng truy cập, sau đó thêm các bước kiểm tra dành riêng cho đích đến.
Linting có thể thay thế hiệu đính không?
Không. Kẻ nói dối sẽ phát hiện các mẫu.Nó không thể xác minh một cách đáng tin cậy sự thật về mặt kỹ thuật, chất lượng lập luận, mục đích của người dùng hoặc liệu một câu có thể hiểu được trong ngữ cảnh hay không.
Kết luận
Tốt Markdown không chỉ là nguồn hiển thị.Nó có bố cục rõ ràng, các liên kết có ý nghĩa, hình ảnh có thể truy cập, hàng rào mã hoàn chỉnh, danh sách nhất quán, bảng hợp lệ và mối quan hệ xác định với nền tảng xuất bản của nó.
Chạy Trình kiểm tra Markdown để kiểm tra cấu trúc nhanh, hãy sử dụng Markdown Trình soạn thảo để xem xét trực quan và chỉ áp dụng các trình định dạng tập trung ở những nơi chúng giúp duy trì nguồn dễ dàng hơn.Kết quả là Markdown dễ mang theo hơn, dễ truy cập hơn và đáng tin cậy hơn trong các chỉnh sửa trong tương lai.