blog.dopana

Quay lại

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:

  1. Tài liệu dài với nhiều heading
  2. Khó tìm kiếm nội dung cụ thể
  3. Người đọc mất thời gian điều hướng
  4. 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ó:

  1. Nó tìm heading đặc biệt (mặc định là “Contents” hoặc “TOC”)
  2. Nó phân tích tất cả heading sau đó
  3. Nó tạo danh sách liên kết đến từng heading
  4. Nó thay thế nội dung giữa heading TOC và heading tiếp theo
Markdown Documentremark-toc PluginTìm heading TOCPhân tích heading sau đóTạo danh sách liên kếtThay thế nội dung TOCMarkdown với TOC hoàn chỉnh

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-toc
bash
yarn add remark-toc
bash
pnpm add remark-toc
bash

[!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:

Và file example.js:

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))
js

Kết quả sau khi chạy:

Tù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)
js

Cá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)
js

Kế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)
markdown

Giớ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)
js

Heading “References” và “Acknowledgments” sẽ không xuất hiện trong TOC.

Hữu ích khi bạn cần prefix cho security reasons:

await remark()
  .use(remarkToc, {prefix: 'user-content-'})
  .process(file)
js

Kết quả:

* [Lịch sử](#user-content-lich-su)
  * [Khám phá](#user-content-kham-pha)
markdown

Tí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:

Để 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)
js

Pipeline đầy đủ#

Markdown Inputremark-tocremark-rehyperehype-slugrehype-autolink-headingsHTML Output

Sử dụng trong Next.js#

Với next.config.mjs#

Vớ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'}]]
        }
      }}
    />
  )
}
jsx

Sử dụng trong Astro#

Với astro.config.mjs#

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}]
    ]
  }
})
js

Security 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>
markdown

Kết quả:

- [Bravo<script>alert(1)</script>](#bravoscriptalert1script)
markdown

Giải pháp:

  • Sanitize markdown trước khi xử lý
  • Sử dụng rehype-sanitize khi 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)
js

Best Practices#

1. Heading placement#

Đặt heading TOC ở vị trí phù hợp - thường sau intro:

# Title

Brief introduction...

## Contents

## Section 1
markdown

2. Độ 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}
js

3. Skip heading không cần thiết#

Skip heading như “References”, “Appendix”:

{skip: 'References|Appendix|Acknowledgments'}
js

4. Tight vs Loose#

  • tight: true cho tài liệu kỹ thuật (compact)
  • tight: false cho 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ăngremark-tocManual TOCTOC Generator
Tự động hóaCóKhôngCó
Cập nhật tự độngCóKhôngCó
Tùy chỉnh caoCóCóHạn chế
Tích dụng remarkCóKhôngKhông
MaintainedCóN/ABiế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.

References#