Tạo Mục Lục Markdown

Tạo Mục Lục Markdown

Phân tích bất kỳ tài liệu Markdown nào và xuất ra Mục Lục có thể điều hướng — định dạng đúng cách GitHub, GitLab hoặc bộ tạo trang tĩnh của bạn mong đợi. Tuỳ chỉnh cấp heading nào được đưa vào, chọn kiểu bullet, indent và cách sinh slug anchor. Output là Markdown thuần bạn có thể dán đầu README, hoặc bấm cho công cụ tự chèn vào vị trí placeholder [TOC] / <!-- toc -->. Mọi xử lý đều ở trình duyệt; tài liệu không rời thiết bị.

Mục Lục Markdown là gì và dùng ở đâu?

Mục Lục Markdown (TOC) là danh sách các liên kết trỏ tới những heading bên trong cùng tài liệu. Khi tài liệu được render trên GitHub, GitLab, GitBook, MkDocs, Docusaurus, Jekyll, Hugo, Notion, Obsidian, hoặc bất kỳ trình xem Markdown nào thêm anchor cho heading, TOC trở thành bản đồ điều hướng trang.

Người đọc lướt TOC để tìm phần cần mà không phải kéo. Người duy trì dùng TOC như công cụ kiểm tra cấu trúc — chỉ liếc qua đã thấy phân cấp tài liệu có hợp lý không.

Nơi thường nhúng TOC:

- Đầu README.md dài, ngay sau mô tả dự án.
- Trên phần API trong tài liệu kỹ thuật.
- Trong ADR (architecture decision record) khi có nhiều phương án.
- Trong biên bản họp hoặc design doc nhiều mục.

Bộ parser phát hiện heading thế nào?

Parser xử lý hai kiểu heading Markdown hỗ trợ:

1. ATX: 1–6 ký tự # ở đầu dòng, theo sau là khoảng trắng, rồi văn bản heading. Hash đuôi tuỳ chọn được bỏ.

# Tiêu đề H1
## Phần H2
### Mục H3

2. Setext: văn bản heading một dòng, dòng dưới là chuỗi = (H1) hoặc - (H2). Kiểu setext cũ và ít dùng hơn, nhưng vẫn là Markdown hợp lệ.

Khi 'Bỏ qua khối mã' bật (mặc định), parser theo dõi khối mã fenced (``` và ~~~) và khối thụt 4 khoảng trắng, bỏ qua các dòng trông giống heading bên trong. Điều này ngăn 'kiểu mã Python: # comment' bị nhầm là heading.

Văn bản sau # mà không có khoảng trắng (`#hashtag`) không phải heading, theo CommonMark. Heading thụt quá 3 khoảng trắng cũng không được nhận là ATX — chúng là văn bản đoạn.

Khác biệt giữa các kiểu slug?

Các bộ render Markdown khác nhau chuyển văn bản heading thành anchor ID hơi khác nhau. Chọn kiểu khớp nơi tài liệu sẽ được render:

- GitHub: chữ thường, khoảng trắng thành gạch ngang, chấm câu bị bỏ, chữ Unicode được giữ. 'Introduction!' → introduction; 'API V2.0' → api-v20. Đây là chuẩn de-facto trên GitHub, gist, GitLab, view Markdown của Notion và nhiều bộ tạo trang tĩnh (Eleventy, Astro).

- GitLab: tương tự GitHub nhưng cho phép underscore trong slug. 'two_words and three' → two_words-and-three.

- CommonMark / Pandoc: nghiêm ngặt chỉ ASCII, bỏ chữ số và chấm câu đầu. '1. Background' → background. Dùng cho Pandoc hoặc bộ render CommonMark nghiêm ngặt.

- Văn bản thuần (không link): chỉ xuất văn bản không có anchor link. Hữu ích khi đích đến không hỗ trợ anchor (một số app chat, email văn bản thuần).

Cách khử trùng lặp anchor hoạt động thế nào?

Khi hai heading có cùng văn bản, slug sẽ đụng nhau và chỉ link đầu hoạt động. Công cụ theo dõi mọi slug đã xuất trong TOC hiện tại và thêm `-1`, `-2`, v.v. cho bản trùng:

## Ví dụ
### Cài đặt → cai-dat
## Chủ đề khác
### Cài đặt → cai-dat-1
### Cài đặt → cai-dat-2

Điều này khớp hành vi thực của GitHub cho heading lặp. GitLab dùng cùng mẫu. Pandoc loại bỏ bản trùng trừ khi bạn bật sơ đồ hậu tố tương tự qua `pandoc --slugify`.

Nếu bạn đổi nguồn rồi tạo lại, hậu tố được gán lại theo thứ tự mới trong tài liệu. Lưu file với TOC đã chèn nếu muốn URL ổn định qua các lần chạy.

Vì sao công cụ thường bỏ qua H1?

Cấp Heading Nhỏ Nhất mặc định là H2. Đây là quy ước phổ biến nhất cho tài liệu Markdown — H1 đầu tiên là chính tiêu đề tài liệu, và TOC mô tả các phần bên trong tiêu đề đó.

Nếu đưa H1 vào TOC bạn sẽ lặp lại tiêu đề, nên hầu hết dự án bắt đầu TOC từ H2.

Nếu tài liệu dùng H1 cho các phần (không có tiêu đề cấp cao nhất), đặt Cấp Heading Nhỏ Nhất thành H1.

Cấp Heading Lớn Nhất kiểm soát độ sâu của TOC. H2–H3 cho tổng quan phẳng. H2–H4 thêm tầng dưới. H2–H6 cho phân cấp đầy đủ — hữu ích cho tài liệu kỹ thuật dài nhưng có thể nhiễu.

'Chèn vào nguồn' làm gì?

Ba hành vi tuỳ vào nguồn:

1. Nếu tài liệu chứa placeholder [TOC], nó thay thế. Đây là quy ước Pandoc / Python-Markdown / WordPress.
2. Nếu chứa HTML comment <!-- toc -->, nó thay thế. Đây là quy ước doctoc / markdown-toc-cli.
3. Ngược lại, chèn TOC ngay sau H1 đầu tiên (hoặc ngay đầu nếu không có H1), cách bằng dòng trống.

Đây là chạy thủ công — công cụ không theo dõi tài liệu hay cập nhật TOC tự động khi bạn sửa heading. Để tự động duy trì TOC, xem doctoc (npm package) hoặc pre-commit hook chạy logic này khi lưu.

TOC chèn vào là Markdown thuần — không có HTML wrapper trừ khi bạn tick 'Bọc bằng heading', thêm dòng `## Mục Lục` trên danh sách.

Có hoạt động với heading không phải tiếng Anh không?

Có. Bộ tạo slug giữ chữ và số Unicode — nên 'Câu hỏi thường gặp', 'Préférences', 'Configuración', '常见问题' đều cho slug tương thích GitHub hợp lệ.

Lưu ý GitHub giữ ký tự Unicode trong slug; URL fragment chứa chúng dưới dạng byte mã hoá %XX khi link được nhấp. Trình duyệt xử lý trong suốt.

Nếu chuyển sang kiểu slug CommonMark, quy tắc nghiêm ngặt hơn — chữ Unicode ngoài [a-z0-9] bị loại. Cho tài liệu đa ngôn ngữ trên GitHub, GitLab hoặc Notion, ưu tiên kiểu GitHub hoặc GitLab.

Văn bản hai chiều (Arabic, Hebrew) hoạt động cả ở văn bản hiển thị và slug. TOC đọc trái-sang-phải trong nguồn, nhưng render đúng trong trình duyệt xử lý bidi.

Khác gì doctoc hay markdown-toc?

doctoc và markdown-toc là công cụ CLI sửa file Markdown tại chỗ. Chúng tuyệt vời cho repository — chạy trong pre-commit hook hoặc CI, bạn luôn có TOC cập nhật trong version control.

Trang này thì ngược lại: phiên bản trình duyệt không cần cài, cùng chức năng. Đánh đổi:

- Dùng nhanh một lần, không cần cài Node/npm, không cần quyền.
- Nhiều kiểu slug trong một UI; doctoc chỉ xuất kiểu GitHub.
- Nút 'Chèn vào nguồn' là ghi một lần vào textarea — sau đó bạn tự copy/save file.
- Mọi xử lý cục bộ — nội dung tài liệu không bị upload.
- Cho bảo trì repo liên tục, doctoc hoặc markdown-toc vẫn là đáp án; cho tạo thủ công thi thoảng, đây nhanh hơn.

Parser xử lý khối mã fenced, heading setext và Unicode tương đương các công cụ CLI đó.

Tính Năng Nổi Bật

• Phân tích heading Markdown kiểu ATX (#) và Setext (=== / ---)
• Khoảng cấp heading tuỳ chỉnh (H1–H6 min, H2–H6 max)
• Kiểu slug GitHub, GitLab, CommonMark + chế độ văn bản thuần
• Tự khử trùng slug với hậu tố -1, -2 (khớp hành vi GitHub)
• Nhận diện Unicode: giữ dấu, chữ không phải Latin, không emoji trong output
• Bỏ qua heading trong khối mã fenced (``` / ~~~) và khối thụt
• Bỏ định dạng bold / italic / inline code / link trong nhãn TOC
• Kiểu bullet: -, *, + hoặc đánh số (1.)
• Cỡ indent: 2, 4 hoặc Tab
• Chèn thay placeholder [TOC] hoặc <!-- toc -->, hoặc sau H1 đầu tiên
• Preview trực tiếp hiển thị TOC dưới dạng danh sách bấm được
• Sao chép TOC vào clipboard
• Có Markdown mẫu để thử nhanh
• 100% phía client — tài liệu không rời trình duyệt
• JavaScript thuần — hoạt động offline sau lần tải đầu