markdown linting accessibility hướng dẫn về phong cách documentation

Hướng dẫn kiểm tra Markdown: 15 lỗi thường gặp và cách khắc phục

Tìm và khắc phục các sự cố Markdown phổ biến bao gồm 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ã bị hỏng, danh sách không nhất quán và bảng không đúng định dạng.

W
WordToMD Đội
·

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 traTại sao nó quan trọngTự động hay thủ công?
Phân cấp tiêu đềBảo toàn cấu trúc tài liệuKẻ nói dối
Văn bản thay thế hình ảnhLàm cho hình ảnh có thể hiểu được mà không cần nhìnKẻ nói dối
Liên kết mô tảCải thiện khả năng truy cập và quétLinter + xem xét thủ công
Hàng rào mã đóngNgă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 íchKẻ nói dối
Khoảng trắng ở cuốiTrá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àngGiữ mục đích trang rõ ràngXem xét thủ công
Danh sách nhất quánNgăn chặn sự lồng ghép bị hỏngXem xét thủ công
Bảng hợp lệGiữ nguyên cấu trúc cộtXem xét thủ công
Tiêu đề duy nhấtNgăn chặn sự nhầm lẫn về neo trùng lặpXem xét thủ công
Cách sử dụng HTML di độngTránh các lỗi cụ thể của trình kết xuấtXem xét thủ công
Đoạn văn có thể đọc đượcCải thiện khả năng hiểuXem 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ố

![](architecture.png)

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

![Request flow from the browser through the API gateway to the orders service](architecture.png)

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.

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:

  1. Trình kết xuất nào sở hữu đầu ra cuối cùng?
  2. Sau này nội dung có cần chuyển đi nơi khác không?
  3. 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:

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.