Tạo Bảng Contents với Remark TOC
Hướng dẫn sử dụng remark-toc để tự động tạo bảng contents cho markdown, giúp tài liệu dễ đọc và điều hướng hơn.
Bạn đã bao giờ viết một tài liệu markdown dài, với hàng chục heading, và phải thủ công tạo bảng contents? Hoặc mỗi khi thêm heading mới, lại phải cập nhật lại danh sách liên kết? 🤔
Trong bài viết này, mình sẽ giới thiệu remark-toc - plugin giúp tự động tạo bảng contents (table of contents) cho markdown một cách dễ dàng.
Tại sao cần Table of Contents?#
Hãy tưởng tượng bạn đang đọc một cuốn sách dày 500 trang mà không có mục lục. Bạn muốn tìm thông tin về một chủ đề cụ thể, nhưng phải lật từng trang một. Rất mệt mỏi và mất thời gian, đúng không?
Trong tài liệu kỹ thuật, vấn đề tương tự xảy ra:
- Tài liệu dài với nhiều heading
- Khó tìm kiếm nội dung cụ thể
- Người đọc mất thời gian điều hướng
- Việc cập nhật thủ công tốn công sức
remark-toc giải quyết vấn đề này bằng cách:
- Tự động hóa - Tạo TOC từ heading có sẵn
- Cập nhật tự động - Khi thêm/sửa heading, TOC tự động cập nhật
- Tùy chỉnh cao - Có thể cấu hình độ sâu, skip heading, v.v.
- Tích hợp dễ dàng - Dùng với unified/remark pipeline
Remark-toc hoạt động như thế nào?#
Hãy tưởng tượng remark-toc như một “người thư mục” thông minh. Khi bạn đưa tài liệu markdown cho nó:
- Nó tìm heading đặc biệt (mặc định là “Contents” hoặc “TOC”)
- Nó phân tích tất cả heading sau đó
- Nó tạo danh sách liên kết đến từng heading
- Nó thay thế nội dung giữa heading TOC và heading tiếp theo
Cài đặt Remark-toc#
Prerequisites#
remark-toc là một unified/remark plugin, nên bạn cần:
- Node.js 16+
- npm hoặc yarn
- Đã cài unified hoặc remark
Cài đặt#
npm install remark-tocbashyarn add remark-tocbashpnpm add remark-tocbash[!TIP] remark-toc là ESM only, nên hãy đảm bảo project của bạn sử dụng ES modules.
Sử dụng cơ bản#
Ví dụ đơn giản#
Giả sử bạn có file example.md:
# Pluto
Pluto là một hành tinh lùn trong vành đai Kuiper.
## Contents
## Lịch sử
### Khám phá
Vào những năm 1840, Urbain Le Verrier đã sử dụng cơ học Newton để dự đoán vị trí của...
### Tên và biểu tượng
Tên Pluto lấy từ thần La Mã của thế giới ngầm, từ một epithet Hy Lạp cho Hades...
### Thông tin bổ sung
Một số thông tin khác về Pluto...
## Quỹ đạo
Chu kỳ quỹ đạo của Pluto khoảng 248 năm...markdownVà file example.js:
import {remark} from 'remark'
import remarkToc from 'remark-toc'
import {read} from 'to-vfile'
const file = await remark()
.use(remarkToc)
.process(await read('example.md'))
console.log(String(file))jsKết quả sau khi chạy:
# Pluto
Pluto là một hành tinh lùn trong vành đai Kuiper.
## Contents
* [Lịch sử](#lich-su)
* [Khám phá](#kham-pha)
* [Tên và biểu tượng](#ten-va-bieu-tuong)
* [Thông tin bổ sung](#thong-tin-bo-sung)
* [Quỹ đạo](#quy-dao)
## Lịch sử
### Khám phá
Vào những năm 1840, Urbain Le Verrier đã sử dụng cơ học Newton để dự đoán vị trí của...
### Tên và biểu tượng
Tên Pluto lấy từ thần La Mã của thế giới ngầm, từ một epithet Hy Lạp cho Hades...
### Thông tin bổ sung
Một số thông tin khác về Pluto...
## Quỹ đạo
Chu kỳ quỹ đạo của Pluto khoảng 248 năm...markdownTùy chọn cấu hình#
remark-toc cung cấp nhiều tùy chọn để tùy chỉnh:
await remark()
.use(remarkToc, {
heading: 'Contents', // Heading để tìm (mặc định: '(table[ -]of[ -])?contents?|toc')
maxDepth: 3, // Độ sâu heading tối đa (mặc định: 6)
skip: 'References', // Skip heading cụ thể
tight: true, // List tight hay loose (mặc định: true)
ordered: false, // Ordered list hay unordered (mặc định: false)
prefix: 'user-content-' // Prefix cho links
})
.process(file)jsCác tính năng nâng cao#
Thay đổi heading TOC#
Nếu bạn muốn dùng heading khác thay vì “Contents”:
await remark()
.use(remarkToc, {heading: 'Structure'})
.process(file)jsĐiều này sẽ tìm heading “Structure” (case-insensitive) thay vì “Contents”.
Ordered list với spacing#
Tạo TOC dạng numbered list với spacing giữa items:
await remark()
.use(remarkToc, {ordered: true, tight: false})
.process(file)jsKết quả:
1. [Lịch sử](#lich-su)
1. [Khám phá](#kham-pha)
2. [Tên và biểu tượng](#ten-va-bieu-tuong)
2. [Quỹ đạo](#quy-dao)markdownGiới hạn độ sâu heading#
Chỉ bao gồm heading đến độ sâu nhất định:
await remark()
.use(remarkToc, {maxDepth: 3})
.process(file)jsĐiều này chỉ bao gồm heading H1, H2, H3 trong TOC.
Skip heading cụ thể#
Loại bỏ heading không muốn trong TOC:
await remark()
.use(remarkToc, {skip: 'References|Acknowledgments'})
.process(file)jsHeading “References” và “Acknowledgments” sẽ không xuất hiện trong TOC.
Thêm prefix cho links#
Hữu ích khi bạn cần prefix cho security reasons:
await remark()
.use(remarkToc, {prefix: 'user-content-'})
.process(file)jsKết quả:
* [Lịch sử](#user-content-lich-su)
* [Khám phá](#user-content-kham-pha)markdownTích hợp với các plugin khác#
remark-toc hoạt động tốt với các plugin remark/rehype khác:
Với rehype-slug và rehype-autolink-headings#
Để tạo TOC có thể click trong HTML:
import {remark} from 'remark'
import remarkToc from 'remark-toc'
import remarkRehype from 'remark-rehype'
import rehypeSlug from 'rehype-slug'
import rehypeAutolinkHeadings from 'rehype-autolink-headings'
import rehypeStringify from 'rehype-stringify'
await remark()
.use(remarkToc) // Tạo TOC
.use(remarkRehype) // Markdown → HTML
.use(rehypeSlug) // Thêm ID cho heading
.use(rehypeAutolinkHeadings) // Thêm anchor links
.use(rehypeStringify) // HTML → string
.process(file)jsPipeline đầy đủ#
Sử dụng trong Next.js#
Với next.config.mjs#
import remarkToc from 'remark-toc'
import remarkGfm from 'remark-gfm'
const nextConfig = {
experimental: {
mdxRs: true,
},
mdxOptions: {
remarkPlugins: [
remarkGfm,
[remarkToc, {heading: 'Contents', maxDepth: 3}]
],
},
}
export default nextConfigjsVới MDX component#
import remarkToc from 'remark-toc'
import {MDXRemote} from 'next-mdx-remote/rsc'
export default function Post({content}) {
return (
<MDXRemote
source={content}
options={{
mdxOptions: {
remarkPlugins: [[remarkToc, {heading: 'Contents'}]]
}
}}
/>
)
}jsxSử dụng trong Astro#
Với astro.config.mjs#
import { defineConfig } from 'astro/config'
import mdx from '@astrojs/mdx'
import remarkToc from 'remark-toc'
export default defineConfig({
integrations: [mdx()],
markdown: {
remarkPlugins: [
[remarkToc, {heading: 'Contents', maxDepth: 3}]
]
}
})jsSecurity Considerations#
[!WARNING] remark-toc copy existing nodes vào TOC, có thể dẫn đến XSS attack nếu markdown chứa malicious content.
Ví dụ nguy hiểm:
## Contents
## Bravo<script>alert(1)</script>markdownKết quả:
- [Bravo<script>alert(1)</script>](#bravoscriptalert1script)markdownGiải pháp:
- Sanitize markdown trước khi xử lý
- Sử dụng
rehype-sanitizekhi chuyển sang HTML - Không trust user input
import rehypeSanitize from 'rehype-sanitize'
await remark()
.use(remarkToc)
.use(remarkRehype)
.use(rehypeSanitize) // Sanitize HTML
.use(rehypeStringify)
.process(file)jsBest Practices#
1. Heading placement#
Đặt heading TOC ở vị trí phù hợp - thường sau intro:
# Title
Brief introduction...
## Contents
## Section 1markdown2. Độ sâu hợp lý#
Đừng đặt maxDepth quá sâu - thường 3-4 là đủ:
// Tốt
{maxDepth: 3}
// Quá sâu, TOC cluttered
{maxDepth: 6}js3. Skip heading không cần thiết#
Skip heading như “References”, “Appendix”:
{skip: 'References|Appendix|Acknowledgments'}js4. Tight vs Loose#
tight: truecho tài liệu kỹ thuật (compact)tight: falsecho tài liệu có nhiều text (readable)
So sánh với các giải pháp khác#
| Tính năng | remark-toc | Manual TOC | TOC Generator |
|---|---|---|---|
| Tự động hóa | Có | Không | Có |
| Cập nhật tự động | Có | Không | Có |
| Tùy chỉnh cao | Có | Có | Hạn chế |
| Tích dụng remark | Có | Không | Không |
| Maintained | Có | N/A | Biến đổi |
Kết luận#
remark-toc là công cụ hữu ích cho bất kỳ ai viết tài liệu markdown dài. Nó giúp:
- Tự động tạo TOC từ heading
- Giảm công sức duy trì
- Tùy chỉnh linh hoạt
- Tích dụng dễ dàng với unified ecosystem
[!TIP] Best practice: Luôn dùng remark-toc với rehype-slug và rehype-autolink-headings để có TOC hoàn chỉnh với clickable links.