Xử lý lỗi chuyển đổi Markdown: bảng, code và hình ảnh

Bạn viết file Markdown sạch đẹp. Bấm "Chuyển đổi". Kết quả? Bảng nát bét, khối mã thành text thường, hình ảnh mất tiêu, công thức LaTeX biến thành ký tự loạn xạ.

Sau khi hỗ trợ hàng ngàn người dùng chuyển đổi Markdown sang Word, PDF và HTML qua MarkFlow, chúng mình đã tổng hợp những lỗi chuyển đổi hay gặp nhất và cách khắc phục. Bài viết này đi qua 15 vấn đề thực tế với giải pháp cụ thể — không lý thuyết suông.

Tra cứu nhanh: Vấn đề và Cách sửa

---

Lỗi liên quan đến bảng

Vấn đề 1: Cột bảng bị lệch hoặc gộp trong Word

Bạn thấy gì: Bảng Markdown gọn gàng biến thành đống hỗn độn trong Word — cột bị gộp, nội dung tràn ra ngoài, hoặc cấu trúc bảng biến mất hoàn toàn.

Tại sao lại thế:

Nguyên nhân phổ biến nhất là cú pháp bảng sai. Bảng trong Markdown khắt khe hơn bạn nghĩ. Thiếu một dấu pipe duy nhất hoặc dòng phân cách không khớp số cột là đủ để phá vỡ toàn bộ bảng.

Đây là những lỗi hay gặp:

<!-- SAI: Thiếu pipe đầu dòng -->
Header 1 | Header 2
--- | ---
Cell 1 | Cell 2

<!-- SAI: Dòng phân cách không khớp số cột -->
| Header 1 | Header 2 | Header 3 |
| --- | --- |
| Cell 1 | Cell 2 | Cell 3 |

Cách sửa:

Luôn dùng cú pháp pipe nhất quán với số cột khớp nhau:

| Header 1 | Header 2 | Header 3 |
|:---------|:--------:|----------:|
| Left     | Center   | Right     |
| Cell 1   | Cell 2   | Cell 3    |

Quy tắc cơ bản:

• Bắt đầu và kết thúc mỗi dòng bằng pipe |
• Dòng phân cách phải có cùng số cột với header
• Dùng dấu hai chấm để căn chỉnh — :--- trái, :---: giữa, ---: phải
• Đừng gộp ô — Markdown chuẩn không hỗ trợ. Nếu cần gộp ô, chỉnh tay trong Word sau khi chuyển đổi

Mẹo: Trước khi chuyển đổi, paste bảng vào linter hoặc trình preview Markdown. Hầu hết editor (VS Code, Typora, Obsidian) sẽ báo ngay nếu bảng bị lỗi.

---

Vấn đề 2: Độ rộng cột không đều trong Word

Bạn thấy gì: Bảng hiển thị đẹp trong Markdown editor, nhưng khi chuyển sang Word thì một cột chiếm 80% trang còn mấy cột kia bị bóp nhỏ xíu.

Tại sao lại thế:

Hầu hết trình chuyển đổi tính độ rộng cột dựa trên chiều dài nội dung. Nếu một ô chứa câu dài hoặc URL còn các ô khác chỉ vài từ, phân bổ sẽ mất cân đối. Khác với HTML, Markdown không có cú pháp để chỉ định độ rộng cột.

Cách sửa:

• Giữ nội dung ô ngắn gọn. Chuyển mô tả dài xuống chú thích hoặc đoạn văn riêng bên dưới bảng
• Chuyển URL dài thành link text: Dùng [Tên link](url) thay vì paste URL trần vào ô
• Dùng MarkFlow — tự động phân bổ độ rộng cột cân đối, cho ra bảng Word dễ đọc hơn

Nếu cần độ rộng cột chính xác, chỉnh trong Word sau khi chuyển đổi: chọn bảng, vào Table Properties, tab Column, đặt preferred width.

---

Vấn đề 3: Ký tự đặc biệt trong bảng phá vỡ hiển thị

Bạn thấy gì: Ký tự pipe | trong nội dung ô phá vỡ cấu trúc cột, hoặc HTML entities hiện thành text thô.

Tại sao lại thế:

Ký tự | là dấu phân cách cột trong bảng Markdown. Khi nội dung ô chứa pipe, parser sẽ hiểu nhầm nó là ranh giới cột mới.

Cách sửa:

Escape ký tự pipe bằng backslash:

| Lệnh | Mô tả |
|:--------|:------------|
| `echo "a \| b"` | Chuyển output qua filter |
| `status: pass\|fail` | Hiển thị trạng thái pass hoặc fail |

Với các ký tự đặc biệt khác trong ô:

• Dùng \| cho pipe
• Dùng HTML entities như & cho dấu & nếu cần
• Bọc nội dung bằng inline code (backtick) để ngăn Markdown xử lý

---

Lỗi liên quan đến khối mã

Vấn đề 4: Khối mã mất syntax highlighting sau khi chuyển đổi

Bạn thấy gì: Code Python hay JavaScript được highlight đẹp đẽ biến thành text một màu trong file Word.

Tại sao lại thế:

Hai nguyên nhân phổ biến:

1. Chưa chỉ định ngôn ngữ — Bạn dùng ba backtick mà không ghi tên ngôn ngữ
2. Trình chuyển đổi không hỗ trợ highlight — Nhiều trình chuyển đổi cơ bản bỏ syntax highlighting khi export ra Word/PDF

Sự khác biệt:

<!-- KHÔNG highlight — thiếu tag ngôn ngữ -->
```
function hello() {
  console.log("Hello");
}
```

<!-- CÓ highlight — đã chỉ định ngôn ngữ -->
```javascript
function hello() {
  console.log("Hello");
}
```

Cách sửa:

Luôn ghi tên ngôn ngữ sau ba backtick mở. Các identifier phổ biến:

Nếu trình chuyển đổi vẫn không cho ra highlight, MarkFlow giữ nguyên syntax highlighting trong cả Word lẫn PDF — code hiện đúng màu, font và indent.

---

Vấn đề 5: Inline code mất định dạng

Bạn thấy gì: Text trong backtick đơn như config.yaml hay npm install hiện ra như text thường trong tài liệu đã chuyển đổi, không có gì phân biệt.

Tại sao lại thế:

Một số trình chuyển đổi xử lý inline code như text thường và không áp dụng style gì. Cú pháp backtick được nhận diện, nhưng output không có font monospace hay màu nền.

Cách sửa:

• Dùng trình chuyển đổi tôn trọng style inline code. MarkFlow render inline code với font monospace và nền nhẹ trong Word
• Tránh backtick lồng nhau. Nếu code chứa backtick, dùng double backtick: `code with `backtick` thành ``code with `backtick` ``
• Đừng lạm dụng inline code để nhấn mạnh — dùng in đậm hoặc in nghiêng. Backtick chỉ dành cho code thật, lệnh, tên file và identifier kỹ thuật

---

Vấn đề 6: Indent và khoảng trắng trong code bị sai

Bạn thấy gì: Khối mã trong Word bị indent sai — hoặc mọi thứ dính sát lề trái, hoặc tab biến thành spacing lộn xộn.

Tại sao lại thế:

Cách chuyển đổi tab thành space khác nhau giữa các Markdown parser và engine render của Word. Một số trình chuyển đổi cắt bỏ khoảng trắng đầu dòng hoặc gộp nhiều space thành một.

Cách sửa:

• Dùng space, không dùng tab, trong khối mã. Hầu hết style guide khuyên dùng 2 hoặc 4 space. Tab bị hiểu khác nhau ở mỗi trình chuyển đổi
• Dùng fenced code block (ba backtick) thay vì indented code block (4 space). Fenced block được parse đáng tin hơn:

<!-- NÊN DÙNG: Fenced code block -->
```python
def nested():
    if True:
        for i in range(10):
            print(i)
```

<!-- TRÁNH: Indented code block (4 space) -->
    def nested():
        if True:
            for i in range(10):
                print(i)

• Kiểm tra output ngay sau khi chuyển đổi. Nếu khoảng trắng sai, lỗi ở trình chuyển đổi chứ không phải Markdown của bạn. Thử công cụ khác hoặc báo bug

---

Lỗi liên quan đến hình ảnh

Vấn đề 7: Hình ảnh không hiển thị sau khi chuyển đổi

Bạn thấy gì: File Word hoặc PDF đã chuyển đổi hiện icon hình ảnh hỏng, khoảng trắng, hoặc alt text thay vì ảnh thật.

Tại sao lại thế:

Đây là lỗi phàn nàn số 1, và gần như luôn do đường dẫn hình ảnh:

1. Đường dẫn tương đối mà trình chuyển đổi không resolve được — ![Alt](./images/photo.png) chạy trong editor vì nó biết file ở đâu. Trình chuyển đổi có thể không biết
2. URL remote cần xác thực — Ảnh trên repo GitHub private, Google Drive hoặc Notion sẽ không tải được khi chuyển đổi
3. Vấn đề protocol — Một số trình chuyển đổi không xử lý đường dẫn file:// hoặc đường dẫn tuyệt đối local
4. Định dạng file không hỗ trợ — Một số trình chuyển đổi gặp khó với SVG, WebP hoặc TIFF

Cách sửa:

Cách đáng tin nhất là dùng URL public:

<!-- Đáng tin nhất: URL tuyệt đối -->
![Architecture diagram](https://your-domain.com/images/diagram.png)

<!-- Cũng đáng tin: nhúng base64 (cho ảnh nhỏ) -->
![Icon](data:image/png;base64,iVBORw0KGgo...)

Với MarkFlow: Kéo thả file .md cùng folder ảnh — đường dẫn tương đối được resolve tự động. Bạn cũng có thể paste Markdown chứa URL ảnh và chúng sẽ được nhúng vào Word.

---

Vấn đề 8: Hình ảnh quá lớn hoặc quá nhỏ trong Word

Bạn thấy gì: Ảnh trông hoàn hảo trong Markdown preview nhưng trong Word thì hoặc tí hon hoặc khổng lồ, phá vỡ layout trang.

Tại sao lại thế:

Markdown không có cú pháp native cho kích thước ảnh. Cú pháp ![alt](url) không nhận tham số width hay height. Hầu hết trình chuyển đổi chèn ảnh ở kích thước pixel gốc, có thể không khớp với chiều rộng trang Word.

Cách sửa:

Một số variant Markdown hỗ trợ kích thước qua HTML:

<!-- Điều khiển kích thước bằng HTML -->
<img src="./diagram.png" alt="Sơ đồ kiến trúc hệ thống" width="600" />

Tuy nhiên không phải trình chuyển đổi nào cũng xử lý HTML tag. Các lựa chọn:

• Resize ảnh gốc về khoảng 600-800px chiều rộng trước khi thêm vào Markdown — phù hợp hầu hết layout Word
• Dùng HTML img tag với width nếu trình chuyển đổi hỗ trợ inline HTML
• Resize sau khi chuyển đổi trong Word: chuột phải vào ảnh, chọn Size and Position, đặt width mong muốn

Kích thước ảnh khuyến nghị cho Word:

• Ảnh full-width: 600-800px
• Sơ đồ inline: 400-500px
• Icon hoặc badge: 100-200px

---

Vấn đề 9: Ảnh nhúng Base64 không chuyển đổi được

Bạn thấy gì: Ảnh nhúng dạng data URI base64 chạy trong preview nhưng hiện hỏng hoặc bị xóa sạch trong tài liệu đã chuyển đổi.

Tại sao lại thế:

Ảnh mã hóa base64 tăng kích thước file khoảng 33%. Một số trình chuyển đổi có giới hạn kích thước cho inline data URI, hoặc đơn giản không parse được format data:image/...;base64,....

Cách sửa:

• Giữ ảnh base64 nhỏ — dưới 100KB sau mã hóa (khoảng 75KB file gốc). Icon và logo nhỏ thì ok; screenshot và ảnh chụp thường không
• Dùng file ảnh thật cho mọi thứ lớn. Host chúng hoặc đặt cạnh file .md
• Kiểm tra tài liệu trình chuyển đổi về hỗ trợ data URI. MarkFlow xử lý ảnh base64 trong cả Word và PDF, với giới hạn thực tế khoảng 2MB mỗi ảnh

---

Lỗi công thức LaTeX và sơ đồ Mermaid

Vấn đề 10: Công thức LaTeX hiện thành text thường

Bạn thấy gì: Thay vì phương trình được render đẹp, Word hiện LaTeX thô: $E = mc^2$ hoặc $$\int_{0}^{1} x^2 dx$$ như text bình thường.

Tại sao lại thế:

Hỗ trợ toán LaTeX không nằm trong Markdown chuẩn hay GFM. Đây là extension cần engine render riêng (KaTeX hoặc MathJax). Hầu hết trình chuyển đổi cơ bản — bao gồm Pandoc không có flag đúng, VS Code không có extension, và Dillinger — không xử lý cú pháp LaTeX.

Cách sửa:

Trước hết, kiểm tra cú pháp:

<!-- Toán inline: dấu dollar đơn -->
Công thức $E = mc^2$ mô tả sự tương đương khối lượng-năng lượng.

<!-- Toán block: dấu dollar đôi -->
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

Sau đó, dùng trình chuyển đổi hỗ trợ LaTeX:

Lỗi LaTeX hay gặp khiến render thất bại:

<!-- SAI: Có space sau dấu $ mở -->
$ E = mc^2 $

<!-- ĐÚNG: Không space sau $ mở -->
$E = mc^2$

<!-- SAI: Thiếu delimiter đóng -->
$$\int_{0}^{1} x^2 dx

<!-- ĐÚNG: Delimiter khớp nhau -->
$$\int_{0}^{1} x^2 dx$$

---

Vấn đề 11: Sơ đồ Mermaid không hiện trong output

Bạn thấy gì: Thay vì flowchart hay sequence diagram, output Word/PDF hiện code Mermaid thô dưới dạng khối mã bình thường.

Tại sao lại thế:

Mermaid là engine render chạy bằng JavaScript. Nó cần browser hoặc môi trường Node.js để tạo sơ đồ. Hầu hết trình chuyển đổi Markdown sang Word xử lý Markdown thuần text và không chạy JavaScript, nên coi block Mermaid như code thường.

Cách sửa:

Kiểm tra cú pháp Mermaid:

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
```

Công cụ render Mermaid sang Word/PDF:

• MarkFlow — Render sơ đồ Mermaid thành ảnh nhúng trong Word
• Typora — Render Mermaid trong preview và export ra PDF
• Pandoc — Cần plugin mermaid-filter (npm install -g mermaid-filter)

Cách xử lý tạm cho trình chuyển đổi không hỗ trợ Mermaid:

1. Dùng Mermaid Live Editor để render sơ đồ
2. Export ra PNG hoặc SVG
3. Thay block Mermaid bằng tham chiếu ảnh trong Markdown
4. Chuyển đổi bình thường

Cách này thêm một bước thủ công nhưng đảm bảo sơ đồ hiện trong output của bất kỳ trình chuyển đổi nào.

---

Lỗi định dạng và cấu trúc

Vấn đề 12: Cấp heading bị sai trong Word

Bạn thấy gì: Hệ thống heading trong Word không khớp Markdown. H2 hiện thành H1, hoặc tất cả heading cùng một cỡ.

Tại sao lại thế:

Hai nguyên nhân phổ biến:

1. Nhiều H1 trong Markdown. Tài liệu chỉ nên có một H1 (tiêu đề). Một số trình chuyển đổi gộp hoặc map lại heading khi phát hiện nhiều H1
2. Trình chuyển đổi map heading Markdown sang Word style khác nhau. Một số công cụ coi heading đầu tiên là tiêu đề tài liệu bất kể cấp nào

Cách sửa:

Tuân theo cấu trúc heading đúng:

# Tiêu đề tài liệu (H1 — dùng đúng một lần)

## Tiêu đề phần (H2 — các phần chính)

### Tiêu đề phụ (H3 — trong các phần)

#### Chi tiết (H4 — hiếm khi cần)

• Đừng nhảy cấp — không đi từ H2 thẳng sang H4
• Dùng H1 một lần duy nhất ở đầu tài liệu, hoặc để trình chuyển đổi thêm từ metadata
• Kiểm tra panel Styles trong Word — heading phải hiện là "Heading 1", "Heading 2", v.v. Nếu hiện "Normal", trình chuyển đổi map sai

---

Vấn đề 13: Danh sách lồng nhau mất indent

Bạn thấy gì: Danh sách lồng nhau cẩn thận — số thứ tự hay bullet — hiện phẳng lì trong Word, mọi mục cùng một cấp.

Tại sao lại thế:

Indent không nhất quán là thủ phạm. Markdown yêu cầu spacing nhất quán để nhận diện cấp lồng. Trộn tab với space, hoặc dùng 2 space chỗ này 3 space chỗ kia, sẽ làm parser bối rối.

Cách sửa:

Dùng 4 space (hoặc 1 tab) cho mỗi cấp, nhất quán:

- Mục cấp một
    - Mục cấp hai
        - Mục cấp ba
    - Quay lại cấp hai
- Quay lại cấp một

1. Mục đầu tiên
    1. Mục con một
    2. Mục con hai
2. Mục thứ hai
    - Bullet dưới số

Lỗi hay gặp:

<!-- SAI: Indent không nhất quán (2 space rồi 3) -->
- Mục A
  - Mục con A (2 space)
   - Mục con B (3 space — parser bị lẫn)

<!-- ĐÚNG: Indent 4 space nhất quán -->
- Mục A
    - Mục con A
    - Mục con B

Nếu trình chuyển đổi vẫn làm phẳng danh sách, thử đổi công cụ. MarkFlow giữ nguyên indent danh sách lồng nhau trong Word, kể cả danh sách hỗn hợp có số và bullet.

---

Vấn đề 14: Chú thích cuối trang biến mất hoặc hỏng

Bạn thấy gì: Tham chiếu footnote như [^1] hiện thành text thường trong tài liệu, và nội dung footnote ở cuối Markdown bị mất hoặc render thành đoạn văn bình thường.

Tại sao lại thế:

Footnote là extension của GFM, không thuộc đặc tả Markdown gốc. Trình chuyển đổi chỉ hỗ trợ Markdown cơ bản sẽ không xử lý cú pháp footnote.

Cách sửa:

Cú pháp footnote đúng:

Nhận định này cần nguồn dẫn[^1]. Thêm một điểm nữa[^note].

[^1]: Smith, J. (2025). "Research Paper Title." Journal Name.
[^note]: Đây là footnote dài với nhiều câu.
    Indent dòng tiếp theo với 4 space.

Kiểm tra:

• Tham chiếu [^id] và định nghĩa [^id]: dùng cùng identifier
• Định nghĩa footnote đặt ở cuối tài liệu (hoặc ít nhất sau tất cả tham chiếu)
• Trình chuyển đổi hỗ trợ footnote GFM — MarkFlow, Pandoc và Typora đều xử lý tốt

---

Vấn đề 15: Emoji hiện thành ô vuông trống

Bạn thấy gì: Emoji như dấu tick, tên lửa, biển cảnh báo hiện thành hình chữ nhật trống hoặc dấu hỏi trong Word.

Tại sao lại thế:

File Word dùng font không chứa ký tự emoji. Khi trình chuyển đổi map text Markdown sang Word, nó áp dụng font chuẩn (Calibri, Times New Roman) có thể không có Unicode emoji.

Cách sửa:

• Sau khi chuyển đổi: Chọn ký tự emoji trong Word, đổi font sang "Segoe UI Emoji" (Windows) hoặc "Apple Color Emoji" (macOS)
• Trước khi chuyển đổi: Nếu emoji quan trọng, cân nhắc thay bằng text tương đương hoặc ảnh
• Dùng trình chuyển đổi xử lý font emoji: MarkFlow map ký tự emoji sang font phù hợp trong Word

---

Phòng ngừa: Cách tránh lỗi chuyển đổi

Hầu hết lỗi chuyển đổi đều phòng tránh được. Hãy biến những thói quen sau thành một phần workflow viết Markdown của bạn.

Kiểm tra trước khi chuyển đổi

Dùng Markdown linter để bắt lỗi cú pháp trước khi chúng thành lỗi chuyển đổi:

# Cài markdownlint CLI
npm install -g markdownlint-cli

# Lint file
markdownlint document.md

Nếu dùng VS Code: cài extension "markdownlint" để kiểm tra real-time.

Dùng preview khớp với output

Preview của editor và output của trình chuyển đổi dùng engine render khác nhau. Cái trông ổn trong VS Code có thể vỡ trong Word. Luôn chạy thử chuyển đổi trước khi export chính thức.

Chuẩn hóa phong cách Markdown

Chọn convention và giữ nhất quán:

• Indent: 4 space cho mỗi cấp lồng
• Ngắt dòng: Một dòng trống giữa các block
• Khối mã: Luôn dùng fenced (không indent), luôn có tag ngôn ngữ
• Hình ảnh: Format đường dẫn nhất quán (toàn bộ relative hoặc toàn bộ absolute)
• Bảng: Pipe đầu và cuối mỗi dòng

Nếu bạn mới làm quen với Markdown, hướng dẫn cú pháp Markdown cơ bản đi qua mọi phần tử chi tiết. Với tính năng nâng cao như footnote và task list, xem hướng dẫn cú pháp mở rộng.

Giữ một file test

Tạo một file Markdown chứa một ví dụ cho mọi phần tử bạn hay dùng — bảng, khối mã, công thức, sơ đồ, danh sách lồng, footnote, emoji. Chạy nó qua trình chuyển đổi mỗi khi cập nhật tool. Cách này bắt regression trước khi ảnh hưởng đến tài liệu thật.

---

Khi nào dùng trình chuyển đổi nào

Các công cụ khác nhau giải quyết bài toán khác nhau:

---

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

H: Tại sao bảng Markdown bị vỡ khi chuyển sang Word? Đ: Nguyên nhân phổ biến nhất là cú pháp pipe không nhất quán — thiếu pipe đầu/cuối hoặc dòng phân cách không khớp số cột. Kiểm tra cú pháp bảng trong Markdown preview trước khi chuyển đổi.

H: Làm sao giữ syntax highlighting trong khối mã khi chuyển sang Word? Đ: Luôn chỉ định ngôn ngữ sau ba backtick mở (ví dụ ```python). Sau đó dùng trình chuyển đổi như MarkFlow giữ nguyên highlighting trong Word.

H: Tại sao hình ảnh biến mất sau khi chuyển Markdown sang Word? Đ: Trình chuyển đổi không resolve được đường dẫn ảnh. Dùng URL tuyệt đối cho ảnh remote, hoặc dùng MarkFlow xử lý đường dẫn tương đối khi upload file .md cùng folder ảnh.

H: Có thể chuyển công thức LaTeX sang Word mà không mất định dạng không? Đ: Được, nhưng cần trình chuyển đổi hỗ trợ LaTeX. MarkFlow, Pandoc (với flag toán) và Typora đều render LaTeX đúng. Trình cơ bản sẽ xuất LaTeX thô thành text thường.

H: Tại sao sơ đồ Mermaid hiện thành code trong tài liệu đã chuyển đổi? Đ: Hầu hết trình chuyển đổi không chạy JavaScript mà Mermaid cần. Dùng MarkFlow để render Mermaid tự động, hoặc render sơ đồ trước thành ảnh bằng Mermaid Live Editor.

H: Làm sao sửa indent danh sách lồng nhau trong Word? Đ: Dùng đúng 4 space cho mỗi cấp lồng trong Markdown. Tránh trộn tab và space. Nếu vẫn bị, thử trình chuyển đổi khác — có cái xử lý danh sách lồng tốt hơn.

---

Tài liệu liên quan

• Chuyển đổi Markdown sang Word — Chuyển đổi với hỗ trợ định dạng đầy đủ
• Chuyển đổi Markdown sang PDF — Tạo PDF sẵn sàng in
• Chuyển đổi Markdown sang HTML — Export HTML sạch, semantic
• Hướng dẫn cú pháp Markdown cơ bản — Nắm vững nền tảng
• Hướng dẫn cú pháp Markdown mở rộng — Tính năng nâng cao và extension GFM
• Hướng dẫn đầy đủ Markdown sang Word — Workflow chuyển đổi từ đầu đến cuối