Danh sách định nghĩa

Danh sách định nghĩa là tính năng mở rộng của Markdown, dùng để tạo danh sách thuật ngữ và phần định nghĩa tương ứng; thường dùng cho bảng thuật ngữ, giải thích thuật ngữ hoặc mô tả tham số.

Cú pháp cơ bản

Định dạng cơ bản

Định dạng cơ bản gồm thuật ngữ ở một dòng riêng, phần định nghĩa ở dòng tiếp theo bắt đầu bằng dấu hai chấm:

Thuật ngữ
: Nội dung định nghĩa

Hiệu ứng hiển thị:

Thuật ngữ : Nội dung định nghĩa

Nhiều thuật ngữ và định nghĩa

Markdown
: Ngôn ngữ đánh dấu nhẹ
: Do John Gruber tạo năm 2004

HTML
: Ngôn ngữ đánh dấu siêu văn bản
: Chuẩn đánh dấu để tạo trang web

Hiệu ứng hiển thị:

Markdown : Ngôn ngữ đánh dấu nhẹ : Do John Gruber tạo năm 2004

HTML : Ngôn ngữ đánh dấu siêu văn bản : Chuẩn đánh dấu để tạo trang web

Cách dùng nâng cao

Định nghĩa nhiều dòng

Nội dung định nghĩa có thể gồm nhiều dòng; các dòng sau cần thụt lề:

Thuật ngữ
: Đây là dòng định nghĩa thứ nhất
  Đây là dòng thứ hai, cần thụt lề ít nhất một khoảng trắng
  
  Đây là đoạn mới, cần thụt lề ít nhất một khoảng trắng và có dòng trống phía trên

Hiệu ứng hiển thị:

Thuật ngữ : Đây là dòng định nghĩa thứ nhất Đây là dòng thứ hai, cần thụt lề ít nhất một khoảng trắng

Đây là đoạn mới, cần thụt lề ít nhất một khoảng trắng và có dòng trống phía trên

Dùng các phần tử Markdown khác trong định nghĩa

Nội dung định nghĩa có thể dùng các phần tử Markdown khác như liên kết, nhấn mạnh, mã, v.v.:

Cú pháp Markdown
: **Markdown** hỗ trợ nhiều định dạng văn bản:
  - *Nghiêng* và **Đậm**
  - [Liên kết](https://www.markdownlang.com)
  - `Mã nội dòng`
  - > Khối trích dẫn
  - Danh sách và phần tử khác

Hiệu ứng hiển thị:

Cú pháp Markdown : Markdown hỗ trợ nhiều định dạng văn bản:

• Nghiêng và Đậm
• Liên kết
• Mã nội dòng

• Khối trích dẫn

• Danh sách và phần tử khác

Danh sách định nghĩa lồng nhau

Một số triển khai Markdown cho phép tạo danh sách định nghĩa lồng nhau:

Thuật ngữ ngoài
: Định nghĩa ngoài

   Thuật ngữ trong
  : Định nghĩa trong
  : Một định nghĩa trong khác

Hiệu ứng hiển thị (trên nền tảng hỗ trợ):

Thuật ngữ ngoài : Định nghĩa ngoài

Thuật ngữ trong : Định nghĩa trong : Một định nghĩa trong khác

Tương thích và khác biệt triển khai

Hỗ trợ trên các nền tảng

Nền tảng/Công cụ	Hỗ trợ danh sách định nghĩa	Cú pháp đặc thù	Hỗ trợ lồng
GitHub Markdown	❌	-	-
GitLab Markdown	✅	Chuẩn	✅
Jekyll (kramdown)	✅	Chuẩn	✅
Hugo	✅	Chuẩn	✅
CommonMark	❌	-	-
VitePress	✅	Chuẩn	✅
Pandoc	✅	Chuẩn	✅

Đầu ra HTML

Phần lớn bộ xử lý Markdown sẽ chuyển danh sách định nghĩa thành các phần tử HTML <dl>, <dt> và <dd>:

<dl>
  <dt>Thuật ngữ</dt>
  <dd>Nội dung định nghĩa</dd>
  
  <dt>Thuật ngữ khác</dt>
  <dd>Định nghĩa khác</dd>
</dl>

Biến thể cú pháp khác nhau

Một số bộ xử lý có thể yêu cầu biến thể cú pháp khác:

<!-- Cú pháp chuẩn -->
Thuật ngữ
: Định nghĩa

<!-- Cú pháp gọn (một số trình) -->
Thuật ngữ: Định nghĩa

<!-- Cú pháp có thêm khoảng trắng (một số trình) -->
Thuật ngữ
  : Định nghĩa

Tình huống sử dụng

Bảng thuật ngữ

Danh sách định nghĩa rất phù hợp để tạo bảng thuật ngữ hoặc từ vựng:

## Bảng thuật ngữ lập trình

API
: Giao diện lập trình ứng dụng; tập quy tắc cho phép các ứng dụng phần mềm giao tiếp với nhau.

Framework
: Thư viện/phần mềm cung cấp cấu trúc chuẩn hoá cho phát triển ứng dụng.

Git
: Hệ thống quản lý phiên bản phân tán, dùng để theo dõi thay đổi trong quá trình phát triển dự án.

IDE
: Môi trường phát triển tích hợp, gồm trình soạn thảo mã và nhiều công cụ phát triển.

Hiệu ứng hiển thị:

Bảng thuật ngữ lập trình

API : Giao diện lập trình ứng dụng; tập quy tắc cho phép các ứng dụng phần mềm giao tiếp với nhau.

Framework : Thư viện/phần mềm cung cấp cấu trúc chuẩn hoá cho phát triển ứng dụng.

Git : Hệ thống quản lý phiên bản phân tán, dùng để theo dõi thay đổi trong quá trình phát triển dự án.

IDE : Môi trường phát triển tích hợp, gồm trình soạn thảo mã và nhiều công cụ phát triển.

Tài liệu API

Danh sách định nghĩa dùng để giải thích tham số/tuỳ chọn trong tài liệu API:

## Tham số yêu cầu

user_id
: **Bắt buộc** - Định danh duy nhất của người dùng.
: Kiểu: `integer`

name
: **Tuỳ chọn** - Tên hiển thị của người dùng.
: Kiểu: `string`
: Mặc định: `null`

status
: **Tuỳ chọn** - Trạng thái người dùng.
: Kiểu: `string`
: Giá trị cho phép: `active`, `inactive`, `suspended`
: Mặc định: `active`

Hiệu ứng hiển thị:

Tham số yêu cầu

user_id : Bắt buộc - Định danh duy nhất của người dùng. : Kiểu: integer

name : Tuỳ chọn - Tên hiển thị của người dùng. : Kiểu: string : Mặc định: null

status : Tuỳ chọn - Trạng thái người dùng. : Kiểu: string : Giá trị cho phép: active, inactive, suspended : Mặc định: active

Mô tả cấu hình

Danh sách định nghĩa cũng phù hợp để giải thích các tuỳ chọn cấu hình:

## Tuỳ chọn cấu hình

debug
: Bật/tắt chế độ gỡ lỗi.
: Kiểu: `boolean`
: Mặc định: `false`
: Ví dụ: `debug: true`

log_level
: Mức độ chi tiết ghi log.
: Kiểu: `string`
: Giá trị cho phép: `error`, `warn`, `info`, `debug`
: Mặc định: `info`
: Ví dụ: `log_level: debug`

max_connections
: Số kết nối đồng thời tối đa được phép.
: Kiểu: `integer`
: Mặc định: `100`
: Ví dụ: `max_connections: 500`

Thực tiễn tốt

Tính nhất quán định dạng

✅ Nên làm:

1. **Giữ phong cách nhất quán giữa thuật ngữ và định nghĩa**:
    - Thuật ngữ dùng danh từ/cụm ngắn gọn
    - Định nghĩa theo dạng câu, viết hoa đầu câu, kết thúc bằng dấu chấm
    - Với định nghĩa nhiều dòng, giữ thụt lề nhất quán

2. **Nhóm hợp lý**:
    - Gom các thuật ngữ liên quan lại
    - Dùng tiêu đề để tách các nhóm danh sách định nghĩa khác nhau

3. **Với thuật ngữ kỹ thuật**:
    - Bao gồm thông tin kiểu dữ liệu
    - Thêm ví dụ
    - Nêu rõ bắt buộc hay tuỳ chọn

❌ Tránh làm:

1. Thuật ngữ quá dài, vượt quá một dòng
2. Dùng quá nhiều định dạng trong thuật ngữ
3. Thiếu phân loại rõ ràng
4. Đưa thông tin không liên quan vào phần định nghĩa

Giải pháp thay thế

Trên nền tảng không hỗ trợ danh sách định nghĩa, có thể mô phỏng bằng định dạng khác:

<!-- Dùng in đậm và thụt lề -->
**Thuật ngữ**
  Nội dung định nghĩa

**Thuật ngữ khác**
  Định nghĩa khác

<!-- Dùng bảng -->
| Thuật ngữ | Định nghĩa |
|------|------|
| API | Giao diện lập trình ứng dụng |
| IDE | Môi trường phát triển tích hợp |

<!-- Dùng tiêu đề và đoạn văn -->
### Thuật ngữ
Nội dung định nghĩa

### Thuật ngữ khác
Định nghĩa khác

Ví dụ ứng dụng thực tế

Tài liệu phần mềm

## Yêu cầu hệ thống

Hệ điều hành
: **Windows**: Windows 10 hoặc mới hơn
: **macOS**: macOS 10.14 (Mojave) hoặc mới hơn
: **Linux**: Ubuntu 18.04+, Debian 10+, CentOS 7+

Phần cứng
: **CPU**: 4 nhân 2.0 GHz hoặc nhanh hơn
: **RAM**: tối thiểu 8GB, khuyến nghị 16GB
: **Lưu trữ**: tối thiểu 10GB trống, nên dùng SSD

Mạng
: Kết nối Internet băng thông rộng (tối thiểu 10 Mbps)
: Cho phép kết nối ra ngoài các cổng: 80, 443, 22

Tài liệu học thuật

## Thuật ngữ nghiên cứu

Tập dữ liệu
: Tập hợp dữ liệu dùng để phân tích/đánh giá.
: Nghiên cứu này dùng mẫu lấy từ kho công cộng (n=1000).

Biến số
: **Biến độc lập**: yếu tố đầu vào do nhà nghiên cứu điều khiển.
  Trong nghiên cứu này, biến độc lập là nhiệt độ môi trường.
  
: **Biến phụ thuộc**: yếu tố đầu ra được đo lường trong nghiên cứu.
  Trong nghiên cứu này, biến phụ thuộc là tốc độ xử lý.
  
: **Biến kiểm soát**: yếu tố được giữ cố định trong thí nghiệm.
  Trong nghiên cứu này gồm độ ẩm và tải xử lý.

Mức ý nghĩa
: Ngưỡng xác suất dùng trong phân tích thống kê để quyết định kết quả có ý nghĩa hay không.
: Nghiên cứu này dùng chuẩn p < 0.05.

Khắc phục sự cố

Danh sách định nghĩa không hiển thị

Nếu danh sách định nghĩa không hiển thị đúng:

1. Kiểm tra nền tảng có hỗ trợ cú pháp danh sách định nghĩa
2. Đảm bảo không có dòng trống giữa thuật ngữ và định nghĩa
3. Xác nhận có khoảng trắng thích hợp trước dấu hai chấm (một số trình có yêu cầu cụ thể)
4. Thử tăng mức thụt lề hoặc dùng biến thể cú pháp khác

Vấn đề với danh sách lồng nhau

Danh sách định nghĩa lồng nhau có thể gặp vấn đề ở một số trình:

1. Tăng cấp độ thụt lề (ví dụ, thuật ngữ bên trong dùng 4 hoặc 8 khoảng trắng)
2. Đảm bảo có dòng trống phù hợp giữa các tầng
3. Nếu vẫn gặp vấn đề, cân nhắc dùng cấu trúc khác (như danh sách thường)

Vấn đề định dạng

Nếu định dạng trong phần định nghĩa chưa đúng:

1. Kiểm tra đã giữ thụt lề đúng cho mọi đoạn và phần tử
2. Đảm bảo các phần tử khối (như khối mã, danh sách) có dòng trống phân tách trong định nghĩa
3. Thử tăng thêm thụt lề

Cú pháp liên quan

• Danh sách - Cú pháp danh sách cơ bản
• Bảng - Trình bày dữ liệu có cấu trúc
• Khối mã rào - Cú pháp khối mã

Công cụ và plugin

• markdown-it-deflist: thêm hỗ trợ danh sách định nghĩa cho markdown-it
• kramdown: trình phân tích Markdown hỗ trợ sẵn danh sách định nghĩa
• remark-definition-list: plugin danh sách định nghĩa cho bộ phân tích remark

---

Danh sách định nghĩa là một tính năng mở rộng mạnh mẽ trong Markdown, đặc biệt phù hợp để viết tài liệu giải thích thuật ngữ, tham số và cấu hình. Dù không phải mọi bộ x