ID tiêu đề
ID tiêu đề là một tính năng mở rộng của Markdown, cho phép thêm định danh tuỳ chỉnh cho tiêu đề, giúp tạo liên kết chính xác và kiểm soát cấu trúc tài liệu.
Cú pháp cơ bản
Thêm ID cho tiêu đề
ID tiêu đề dùng cú pháp ngoặc nhọn, đặt sau nội dung tiêu đề:
## Tiêu đề của tôi {#custom-id}Hiệu ứng hiển thị:
HTML đầu ra sẽ gắn ID tuỳ chỉnh này lên phần tử tiêu đề:
<h2 id="custom-id">Tiêu đề của tôi</h2>ID cho nhiều cấp tiêu đề
Mọi cấp tiêu đề đều có thể gắn ID tuỳ chỉnh:
# Tiêu đề cấp 1 {#first-level}
## Tiêu đề cấp 2 {#second-level}
### Tiêu đề cấp 3 {#third-level}
#### Tiêu đề cấp 4 {#fourth-level}Tình huống sử dụng
Tạo liên kết neo
Với ID tuỳ chỉnh, bạn có thể tạo liên kết đến phần cụ thể trong tài liệu:
[Nhấn để chuyển đến tiêu đề của tôi](#custom-id)
...nội dung khác...
## Tiêu đề của tôi {#custom-id}Hiệu ứng hiển thị:
Nhấp liên kết sẽ chuyển thẳng đến tiêu đề có custom-id.
Liên kết từ bên ngoài đến phần cụ thể
ID tuỳ chỉnh cũng thuận tiện để liên kết từ tài liệu ngoài vào phần cụ thể:
[Liên kết đến một mục cụ thể của tài liệu khác](other-doc.html#specific-section)Chia sẻ URL đến mục cụ thể
Tiêu đề có ID có thể chia sẻ qua URL, trỏ đến mục cụ thể trong tài liệu:
https://www.markdownlang.com/documentation.html#installation-guideCách dùng nâng cao
ID cho tiêu đề nhiều từ
Khi tiêu đề có nhiều từ, ID thường dùng dấu gạch nối để nối từ:
## Hướng dẫn cài đặt và cấu hình {#installation-and-configuration}Tạo mục lục và ID tiêu đề
Nhiều bộ xử lý Markdown tự động sinh ID từ nội dung tiêu đề. Nhờ ID tuỳ chỉnh, liên kết trong mục lục sẽ không bị ảnh hưởng nếu bạn đổi nội dung tiêu đề:
## Bắt đầu {#getting-started}Dù sau này đổi tiêu đề thành "Bắt đầu sử dụng", liên kết vẫn hợp lệ vì ID không thay đổi.
Quốc tế hoá và ký tự không phải tiếng Anh
Với tiêu đề không phải tiếng Anh, ID tuỳ chỉnh đặc biệt hữu ích vì cung cấp định danh tiếng Anh ổn định:
## Hướng dẫn cài đặt {#installation}
## Cách sử dụng {#usage}
## Câu hỏi thường gặp {#faq}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ợ ID tiêu đề | Cú pháp |
|---|---|---|
| GitHub Markdown | ✅ | {#id} |
| GitLab Markdown | ✅ | {#id} |
| Jekyll (kramdown) | ✅ | {:#id} hoặc {#id} |
| Hugo | ✅ | {#id} |
| CommonMark | ❌ | Không hỗ trợ |
| VitePress | ✅ | {#id} |
| Pandoc | ✅ | {#id} |
Quy tắc tạo ID tự động
Khi không cung cấp ID tuỳ chỉnh, đa số bộ xử lý Markdown sẽ tự sinh ID từ nội dung tiêu đề:
- Chuyển thành chữ thường
- Xoá hoặc thay thế ký tự đặc biệt
- Thay dấu cách bằng dấu gạch nối
- Xoá dấu gạch nối lặp
- Đảm bảo tính duy nhất (thường bằng hậu tố số)
Ví dụ:
| Tiêu đề | ID tự động sinh |
|---|---|
## Getting Started | #getting-started |
## FAQ & Help | #faq-help |
## Nhanh bắt đầu | #nhanh-bat-dau hoặc #section-1 (tuỳ nền tảng) |
Thực tiễn tốt
Quy ước đặt tên ID tiêu đề
✅ Nên làm:
1. **Dùng ID ngắn gọn, có tính mô tả**:
- `{#installation}`
- `{#api-reference}`
- `{#troubleshooting}`
2. **Giữ phong cách đặt tên nhất quán**:
- Tất cả chữ thường
- Dùng gạch nối để tách từ
- Tránh dùng gạch dưới hoặc camelCase
3. **Giữ ID ổn định**:
- Tránh đổi ID thường xuyên
- Khi sửa nội dung tiêu đề, giữ nguyên ID cũ
❌ Tránh làm:
1. Dùng ký tự đặc biệt (như `!@#$%^&*()`)
2. Dùng ID không mô tả (như `{#section1}`)
3. Tạo ID quá dài
4. Dùng dấu cách hoặc dấu câu trong IDCấu trúc tài liệu và ID tiêu đề
Với tài liệu lớn, nên dùng ID chuẩn hoá cho các phần chính để dễ điều hướng:
# Tài liệu sản phẩm {#product-docs}
## Giới thiệu {#introduction}
## Cài đặt {#installation}
### Cài đặt Windows {#installation-windows}
### Cài đặt macOS {#installation-macos}
### Cài đặt Linux {#installation-linux}
## Cấu hình {#configuration}
## Tham chiếu API {#api-reference}
## Câu hỏi thường gặp {#faq}Ví dụ ứng dụng thực tế
ID tiêu đề trong tài liệu kỹ thuật
ID tiêu đề giúp người dùng liên kết trực tiếp tới phần cụ thể trong tài liệu kỹ thuật:
# Tài liệu API {#api-documentation}
## Xác thực {#authentication}
### Lấy khoá API {#get-api-key}
### Xác thực OAuth {#oauth}
## Endpoint {#endpoints}
### Endpoint người dùng {#endpoints-users}
### Endpoint sản phẩm {#endpoints-products}ID tiêu đề trong bài báo học thuật
Bài báo học thuật có thể dùng ID tiêu đề để tạo trích dẫn và tham chiếu chéo:
# Phương pháp nghiên cứu {#methodology}
Như được thể hiện ở [Kết quả nghiên cứu](#results), phương pháp của chúng tôi hoạt động tốt trong nhiều ca kiểm thử.
...
# Kết quả nghiên cứu {#results}
Phần này trình bày kết quả thí nghiệm được mô tả ở [Phương pháp nghiên cứu](#methodology).Khắc phục sự cố
ID tiêu đề không hoạt động
Nếu ID tiêu đề không hoạt động:
- Kiểm tra nền tảng có hỗ trợ ID tiêu đề tuỳ chỉnh
- Xác nhận cú pháp đúng (thường là
{#id}) - Kiểm tra có ký tự không hợp lệ trong ID
- Thử dùng bộ xử lý Markdown khác
Xung đột ID
Nếu một tài liệu có nhiều ID trùng nhau, hành vi liên kết có thể không đoán trước được:
## Vấn đề {#issue} <!-- ID đầu tiên -->
...
## Câu hỏi thường gặp {#issue} <!-- ID trùng, có thể gây vấn đề -->Giải pháp tránh xung đột ID:
## Vấn đề {#issue-description}
...
## Câu hỏi thường gặp {#common-issues}Khoảng trắng và ký tự đặc biệt
Một số bộ xử lý Markdown xử lý khoảng trắng và ký tự đặc biệt trong ID không nhất quán:
<!-- Có thể gây lỗi trên một số nền tảng -->
## Cài đặt nâng cao {#advanced settings}
<!-- Cách an toàn hơn -->
## Cài đặt nâng cao {#advanced-settings}Cú pháp liên quan
- Liên kết - Cú pháp liên kết cơ bản
- Mục lục - Tạo mục lục tự động
- Chú thích - Thêm tham chiếu và chú giải
Công cụ và plugin
Tự động tạo mục lục
Nhiều công cụ có thể tự động tạo mục lục dựa trên tiêu đề và ID tiêu đề:
[[toc]]
# Chương một {#chapter-1}
## Mục 1.1 {#section-1-1}
# Chương hai {#chapter-2}Công cụ kiểm tra ID tiêu đề
- markdownlint: có thể cấu hình để kiểm tra tính nhất quán ID tiêu đề
- remark-lint: cung cấp kiểm tra và tự động sửa ID tiêu đề
- markdown-toc: tự động tạo mục lục có liên kết
ID tiêu đề là công cụ quan trọng để cải thiện tính hữu dụng và khả năng truy cập của tài liệu Markdown. Bằng cách dùng ID tiêu đề chuẩn hoá, bạn có thể tạo cấu trúc liên kết ổn định, thuận tiện cho điều hướng và tham chiếu, giúp tài liệu chuyên nghiệp và dễ sử dụng hơn.