Chuyển Markdown sang Word bằng dòng lệnh: hướng dẫn Pandoc

Nếu bạn muốn chuyển Markdown sang Word từ dòng lệnh, câu trả lời là pandoc, và toàn bộ công việc gói gọn trong một dòng:

pandoc report.md -f gfm -o report.docx

Lệnh đó xử lý được phần lớn tài liệu. Điều mà các bài hướng dẫn "một dòng là xong" không nói cho bạn là nó dừng hoạt động ở đâu — và một phần những gì được viết về giới hạn của pandoc đơn giản là đã lỗi thời. Khi tôi thử nghiệm với Pandoc 3.7, một vài kết quả khiến tôi bất ngờ. Cụ thể, tôi chạy pandoc 3.7.0.2 trên một tài liệu thử nghiệm chứa đầy bảng, danh sách công việc (task list), công thức LaTeX và một sơ đồ Mermaid, sau đó giải nén tệp .docx thu được để xem chính xác bên trong có gì.

Bài hướng dẫn này đi qua từng bước: cài đặt, các lệnh đáng nhớ, tùy chỉnh kiểu DOCX, chuyển đổi hàng loạt và — dựa trên bài thử nghiệm đó — một bản đồ trung thực về nơi pandoc gặp giới hạn và khi nào công cụ chuyển đổi online là lựa chọn tốt hơn.

👉 Xem ngay kết quả thử nghiệm | Đến phần so sánh dòng lệnh vs online

Cài đặt Pandoc

Pandoc là một tệp nhị phân duy nhất, có bộ cài cho mọi nền tảng lớn:

• macOS: brew install pandoc
• Windows: winget install --id JohnMacFarlane.Pandoc (hoặc bộ cài MSI)
• Debian/Ubuntu: sudo apt install pandoc

Một lưu ý trước khi bạn tin vào gói hệ thống cũ: kho phần mềm của các bản phân phối Linux thường phát hành những phiên bản pandoc tụt hậu nhiều năm. Ubuntu LTS đã phân phối bản 2.x trong thời gian dài, trong khi dòng phát hành hiện tại là 3.x — và như bạn sẽ thấy bên dưới, tuổi của phiên bản quyết định những gì được chuyển đổi trọn vẹn. Kiểm tra phiên bản của bạn bằng pandoc --version.

Giải thích lệnh chuyển đổi cơ bản

Lệnh tối giản vẫn chạy tốt, nhưng trong các dự án thực tế, những cờ (flag) sau đảm nhận phần lớn công việc:

pandoc report.md -f gfm -o report.docx --toc

Tại sao dùng -f gfm thay vì phương ngữ Markdown mặc định của pandoc? Vì Markdown mà hầu hết mọi người viết ngày nay — trong README trên GitHub, trong kết quả của ChatGPT và Claude, trong bản xuất từ Notion — chính là GFM. Phương ngữ mặc định của pandoc thiên về học thuật hơn: nó bật chú thích cuối trang và trích dẫn nhưng diễn giải một vài cấu trúc theo cách khác. Nếu nguồn của bạn đến từ trợ lý AI hoặc công cụ dành cho lập trình viên, gfm là lựa chọn an toàn hơn.

Ghi chú về công thức toán: với trình đọc GFM, cú pháp $...$ và $$...$$ hoạt động bình thường trong pandoc hiện tại. Công thức trở thành phương trình Word gốc, không phải hình ảnh. Chúng ta sẽ nói kỹ hơn bên dưới, vì đây là hành vi của pandoc bị mô tả sai nhiều nhất trên mạng.

Tùy chỉnh kiểu đầu ra bằng reference document

Một tệp DOCX do pandoc tạo ra sẽ mở trong Word với kiểu dáng chung chung. Nếu tài liệu phải khớp với mẫu của công ty, bạn không sửa điều đó bằng cờ lệnh — bạn dùng một reference document (tài liệu tham chiếu).

Quy trình gồm ba bước:

1. Tạo mẫu mặc định của pandoc làm điểm khởi đầu:

   pandoc -o custom-reference.docx --print-default-data-file reference.docx
   

2. Mở custom-reference.docx trong Word và chỉnh sửa các kiểu (styles) — Heading 1, Normal, Table, khối mã. Nội dung văn bản của tệp này bị bỏ qua; chỉ có kiểu và thiết lập trang được giữ lại.

3. Chuyển đổi với mẫu đã áp dụng:

   pandoc report.md -f gfm --reference-doc=custom-reference.docx -o report.docx
   

Tài liệu hướng dẫn pandoc liệt kê những tên kiểu nào được tôn trọng. Mô hình tư duy giúp bạn nắm được điều này: bạn không định dạng một tài liệu, bạn dạy pandoc bộ kiểu Word của tổ chức mình một lần duy nhất, rồi tái sử dụng chúng cho mọi lần chuyển đổi sau đó.

Chuyển đổi hàng loạt nhiều tệp

Đây chính là nơi dòng lệnh thực sự vượt trội so với bất kỳ công cụ web nào. Chuyển đổi cả một thư mục:

Bash (macOS/Linux):

for f in docs/*.md; do
  pandoc "$f" -f gfm -o "${f%.md}.docx"
done

PowerShell (Windows):

Get-ChildItem docs -Filter *.md | ForEach-Object {
  pandoc $_.FullName -f gfm -o ($_.FullName -replace '\.md$', '.docx')
}

Và vì pandoc chỉ là một phụ thuộc duy nhất, nó tích hợp vào CI mà không cần thủ tục rườm rà. Một bước GitHub Actions tự tạo lại bản Word của tài liệu sau mỗi lần push trông như sau:

- uses: pandoc/actions/setup@v1
- run: |
    for f in docs/*.md; do
      pandoc "$f" -f gfm --reference-doc=brand.docx -o "out/$(basename "${f%.md}").docx"
    done

Nhiều nhóm dùng mẫu này để duy trì một bản sao Word của wiki Markdown phục vụ kiểm tra tuân thủ hoặc bàn giao cho khách hàng. Nếu bạn chuyển đổi cùng một bộ tệp quá hai lần, đoạn script này lập tức xứng đáng với công sức bỏ ra.

Giới hạn thực tế của Pandoc (kiểm chứng trên 3.7)

Đây là bài thử nghiệm tôi đã chạy. Một tệp Markdown chứa một bảng, một task list, công thức toán nội dòng ($E = mc^2$), một phương trình hiển thị nhiều dòng, một sơ đồ luồng Mermaid và một khối cảnh báo (alert) kiểu GFM. Tệp được chuyển đổi bằng pandoc 3.7.0.2, sau đó tôi giải nén .docx và đọc trực tiếp word/document.xml. Có ba phát hiện.

Công thức toán hoạt động tốt hơn những gì bạn từng nghe

Phần XML của tài liệu chứa hai khối <m:oMath> — mỗi phương trình một khối. Đó là OMML, định dạng phương trình gốc của Word. Cả hai phương trình đều chỉnh sửa được đầy đủ trong trình soạn phương trình của Word, hiển thị ở chất lượng in ấn và giữ nguyên khi sao chép sang các tài liệu Office khác.

Điều này mâu thuẫn với một tuyên bố bạn vẫn thấy trong các hướng dẫn cũ (và cho đến gần đây, trong chính một bài hướng dẫn của chúng tôi): rằng LaTeX phức tạp sẽ bị chuyển thành hình ảnh. Với pandoc hiện tại, điều đó không xảy ra. Công thức LaTeX chuẩn — phân số, tổng sigma, chữ cái Hy Lạp, chỉ số dưới — được chuyển thành phương trình gốc ngay lập tức, không cần cấu hình thêm.

Ranh giới trung thực là: pandoc xử lý cú pháp toán LaTeX chuẩn, chứ không phải LaTeX tùy ý. Macro \newcommand tự định nghĩa, hình vẽ TikZ và các môi trường phụ thuộc gói sẽ không đi qua được. Và nếu bản phân phối của bạn cài pandoc 2.x, hành vi sẽ khác — hãy kiểm tra pandoc --version trước khi đổ lỗi cho công cụ.

Mermaid mới là điểm gãy thật sự

Sơ đồ luồng Mermaid đã không trở thành một sơ đồ. Nó đi qua dưới dạng văn bản đơn cách nguyên văn — mã nguồn flowchart LR thô, được định dạng như một khối mã. Phần XML của tài liệu cho thấy không có bất kỳ đối tượng vẽ (drawing object) nào.

Điều này giờ đây quan trọng hơn nhiều so với năm năm trước, vì các trợ lý AI rất thích Mermaid. Hỏi ChatGPT hoặc Claude về một bản tổng quan kiến trúc, khả năng cao câu trả lời sẽ kèm một khối mã mermaid. Chuyển cuộc trò chuyện đó bằng pandoc và tài liệu Word của bạn sẽ chứa thứ trông như mã nguồn còn sót lại. Nếu đó là quy trình làm việc của bạn, bài hướng dẫn xuất kết quả ChatGPT sang Word của chúng tôi đề cập các chi tiết riêng cho nội dung AI.

Có một cách khắc phục trên CLI: mermaid-filter, một bộ lọc pandoc kết xuất sơ đồ ngay trong quá trình chuyển đổi. Nó hoạt động, nhưng hãy cân nhắc chi phí cài đặt một cách thẳng thắn — đó là một gói npm kéo theo cả Chromium chạy nền qua Puppeteer, và lệnh pandoc trở thành pandoc -F mermaid-filter .... Với một pipeline tài liệu chuyển đổi sơ đồ hằng ngày, chi phí thiết lập đó được bù đắp dần. Với một bản báo cáo phải nộp chiều nay, đó là đường vòng.

Những mất mát nhỏ ở rìa

Hai phát hiện lặng lẽ hơn từ cùng bài thử nghiệm. Khối cảnh báo GFM (> [!NOTE]) giữ được văn bản nhưng mất phần trình bày callout có màu — trong Word chúng hiện ra như trích dẫn khối thông thường. Và các mục task list đến nơi dưới dạng văn bản danh sách thuần thay vì ô đánh dấu (checkbox) của Word. Không lỗi nào làm hỏng tài liệu; cả hai đều làm phẳng những định dạng mà tác giả hẳn đã chọn có chủ đích. Nếu quá trình chuyển đổi của bạn trục trặc theo những cách khác, chúng tôi đã tổng hợp các lỗi thường gặp trong bài các vấn đề phổ biến khi chuyển đổi Markdown.

Dòng lệnh hay công cụ chuyển đổi online?

Sau đợt thử nghiệm đó, đây là khung quyết định mà tôi sẽ thực sự dùng:

Cả hai con đường đều chính đáng. Pandoc xứng đáng có chỗ trong mọi pipeline lặp lại. Với trường hợp một lần kiểu "tôi cần tệp .docx này trong năm phút nữa" — nhất là khi có Mermaid — thì một công cụ chuyển Markdown sang Word online miễn phí cho bạn một tài liệu sạch sẽ với cả phương trình lẫn sơ đồ đã được kết xuất, không phải cài gì cả.

Câu hỏi thường gặp

Q: Có cách chuyển markdown sang word mà không cần cài đặt gì không?
A: Không thể từ dòng lệnh — pandoc bắt buộc phải cài đặt. Nếu việc cài phần mềm không khả thi, công cụ chuyển đổi chạy trên trình duyệt là lối đi thực tế; quá trình chuyển đổi diễn ra ở phía máy chủ và bạn tải về tệp .docx hoàn chỉnh.

Q: Pandoc có chuyển công thức LaTeX thành phương trình Word thật không?
A: Có. Trong bài thử nghiệm của chúng tôi với pandoc 3.7.0.2, cả công thức nội dòng lẫn công thức hiển thị đều trở thành phương trình OMML gốc, chỉnh sửa được trong trình soạn phương trình của Word. Ngoại lệ là các phiên bản pandoc rất cũ và macro LaTeX tự định nghĩa.

Q: Tại sao sơ đồ Mermaid của tôi hiện ra dưới dạng mã trong Word?
A: Pandoc coi khối mã mermaid là mã nguyên văn — nó không kết xuất sơ đồ. Hoặc thêm mermaid-filter vào pipeline của bạn (cần Node.js), hoặc dùng công cụ chuyển đổi có sẵn khả năng kết xuất Mermaid.

Q: Làm sao giữ được phông chữ và kiểu tiêu đề của công ty tôi?
A: Dùng --reference-doc=template.docx. Chỉnh các kiểu trong tệp mẫu đó một lần trong Word; pandoc sẽ áp dụng chúng cho mọi lần chuyển đổi. Nội dung trong tệp mẫu bị bỏ qua, chỉ có kiểu được giữ lại.

Q: -f markdown và -f gfm khác nhau thế nào?
A: markdown là phương ngữ mở rộng riêng của pandoc (chú thích cuối trang, trích dẫn); gfm khớp với những gì GitHub, ChatGPT và hầu hết công cụ hiện đại tạo ra — bảng, task list, gạch ngang chữ. Với Markdown do AI sinh ra hoặc do lập trình viên viết, gfm ít gây bất ngờ hơn.

Q: Pandoc có chuyển ngược Word về Markdown được không?
A: Có — đảo ngược các tham số: pandoc report.docx -o report.md. Chuyển đổi khứ hồi sẽ mất một số định dạng riêng của Word (hộp văn bản, bình luận), nên hãy xem đây là một cuộc di chuyển nội dung, không phải một vòng lặp không mất mát.

Tài nguyên liên quan

• Hướng dẫn đầy đủ chuyển Markdown sang Word: toàn cảnh các phương án chuyển đổi ngoài dòng lệnh
• ChatGPT sang Word: quy trình Markdown cho tài liệu do AI tạo ra
• Markdown sang PDF: khi sản phẩm bàn giao là PDF
• Các vấn đề phổ biến khi chuyển đổi Markdown: cách sửa bảng vỡ, lỗi mã hóa ký tự và định dạng bị lệch

Kết luận

Pandoc vẫn là câu trả lời đúng cho bài toán "chuyển Markdown sang Word từ dòng lệnh" — một lệnh cho một tệp, một đoạn script ngắn cho cả thư mục, --reference-doc cho bộ kiểu của công ty. Thử nghiệm của chúng tôi cho thấy khả năng xử lý công thức toán của nó tốt hơn danh tiếng: LaTeX chuẩn trở thành phương trình Word thật, chỉnh sửa được.

Khoảng trống thực sự nằm ở phần hình ảnh: sơ đồ Mermaid đến nơi dưới dạng mã nguồn trừ khi bạn lắp thêm chuỗi bộ lọc chạy trên Node. Vậy nên hãy chọn theo quy trình làm việc. Pipeline lặp lại với tài liệu thuần văn bản: viết script với pandoc. Một tài liệu duy nhất có sơ đồ và hạn nộp gấp: chuyển đổi ngay trên trình duyệt để giữ nguyên cả phương trình lẫn sơ đồ luồng.

Tài liệu tham khảo

• Pandoc User's Guide — tài liệu chính thức: trình đọc, trình ghi, --reference-doc, xử lý công thức toán
• Installing pandoc — bộ cài chính thức cho mọi nền tảng
• mermaid-filter — bộ lọc pandoc của cộng đồng để kết xuất sơ đồ Mermaid
• pandoc/actions — GitHub Actions chính thức cho pandoc trong CI