Markdown table vs CSV | Khi nào dùng bảng MD, khi nào giữ CSV【2026】

Team VN hay đứng giữa hai thói quen: PM sống trên Google Sheets, dev sống trên GitHub README. Một bên gửi file .csv, một bên đòi “paste bảng vào PR cho dễ review”. Chọn sai định dạng → hoặc reviewer phải tải file mới mở được, hoặc README thành tường | không cuộn nổi trên điện thoại.

Bài Markdown table vs CSV trả lời câu hỏi khi nào dùng cái nào — bổ sung góc platform (GitHub/Notion) đã viết riêng. Ở đây trọng tâm là vòng đời dữ liệu, diff Git, và ngưỡng chuyển định dạng.

Bài viết này giúp bạn

• Phân biệt hiển thị docs vs nguồn dữ liệu
• Bảng quyết định theo cột / tần suất / người đọc
• Case: SaaS pricing, log lỗi, backlog Notion
• Quy trình convert CSV → MD an toàn
• Dấu hiệu “đã đến lúc bỏ table trong README”

---

Hai định dạng, hai việc

	Markdown table	CSV (hoặc TSV)
Mục đích chính	Đọc trong .md, Issue, Wiki	Lưu / import / tính toán
Mở bằng	GitHub, VS Code preview, HackMD	Excel, Sheets, pandas, DB
Merge ô	Không	Có trên spreadsheet (mất khi export thô)
Diff Git	Dễ đọc nếu bảng ngắn	Diff từng dòng; conflict ít “vỡ cột pipe” hơn MD rộng
Filter / sort	Không (trừ khi platform biến thành DB)	Có

Quy tắc nhanh: hỏi “bảng này còn bị sửa số liệu tuần sau không?”

• Có → CSV/Sheets là nguồn; MD chỉ là snapshot
• Không, chỉ để đọc một lần trong docs → Markdown table

---

Ma trận quyết định

Ngưỡng thực dụng (không cứng nhắc)

• ≤ ~10 cột, ≤ ~20 hàng, ít sửa → MD ổn trong README
• > ~15 cột hoặc cập nhật thường → CSV/Sheets + link; MD chỉ “Top thay đổi”
• Cần tính SUM/AVG → đừng dùng pipe table làm spreadsheet

---

Vòng đời dữ liệu (góc team outsource)

Luồng hay gặp:

1. Khách / BA giữ Google Sheets
2. Dev cần snippet trong PR / README
3. Non-dev cần Notion để filter theo Owner

Sai: copy Sheets → Markdown table khổng lồ → tuần sau sửa giá → conflict Git trên 80 dòng |.
Đúng: Sheets/CSV = nguồn; mỗi lần release trích bảng nhỏ vào CHANGELOG bằng generator; Notion Database import CSV định kỳ.

Như vậy MD không phải “bản sao đầy đủ” — chỉ là mặt đọc cho Git.

---

Diff Git: vì sao bảng MD rộng đau

Sửa một ô Có → Không trong bảng 12 cột tạo hunk khó skim: reviewer không biết bạn đổi đúng một cell hay lệch cả hàng pipe.

CSV một cột một ý trên dòng (tuỳ style) vẫn có noise, nhưng ít vỡ cấu trúc hiển thị hơn khi conflict merge. Với docs: bảng ngắn MD vẫn thắng vì không cần mở tool ngoài để hiểu thay đổi.

---

Ví dụ A — Pricing trên README

Nên MD:

| Gói | Seat | Giá/tháng |
| --- | ---: | --------: |
| Free | 3 | 0 |
| Pro | 20 | 499000 |

Ba cột, ít đổi — reader thấy ngay trên GitHub mobile.

Không nên MD: file 40 cột “Price_VN_Tier1…Tier12” copy nguyên từ finance sheet. Để pricing.csv trong /docs hoặc link Sheets nội bộ; README chỉ 3 gói public.

---

Ví dụ B — Backlog lỗi từ CSV

QA export:

id,severity,owner,status
E-12,Timeout login,An,open
E-15,Sai encoding UTF-8 tên file,Binh,open

• Standup trên Notion Database → import CSV
• Issue GitHub tuần này chỉ 2 bug P0 → convert 2 hàng sang Markdown table trong mô tả Issue

Đừng paste cả 200 dòng CSV thành table MD trong một Issue.

---

Convert CSV → Markdown (khi đã chọn MD)

1. Mở nguồn CSV/Sheets, cắt còn các cột cần đọc
2. Copy vùng → Tạo bảng Markdown
3. Convert → kiểm tra header + --- + escape |
4. Preview GitHub
5. Ghi chú trong PR: “snapshot từ pricing.csv ngày …” nếu số liệu có thể lệch nguồn

Tool chạy local trên trình duyệt — phù hợp bảng nội bộ trước khi public.

Markdown → CSV đầy đủ ít khi cần; nếu cần phân tích lại, lấy từ nguồn Sheets chứ đừng parse ngược pipe table đã chỉnh tay.

---

Notion: paste MD vs import CSV

Nhu cầu	Cách
Đoạn bảng trong trang hướng dẫn	Paste Markdown table
Quản lý task / inventory	CSV → Database
Đổi filter theo người	Database (CSV), không phải pipe

Paste MD vào Notion có thể mất alignment và nhạy với | — chi tiết trong GitHub vs Notion. Ở đây chỉ nhớ: Database ≠ bảng MD.

---

Dấu hiệu nên bỏ Markdown table trong README

• Mỗi sprint conflict trên cùng file bảng
• Mobile phải scroll ngang cả màn hình
• Người non-dev hỏi “file Excel đâu?” sau khi đọc README
• Bạn bắt đầu viết script “sync MD từ CSV” thủ công hàng tuần

→ Chuyển nguồn sang CSV/Sheets; README giữ đoạn văn + bảng tóm tắt 5 dòng.

---

Checklist quyết định 60 giây

1. Người đọc chính: dev trên GitHub hay BA trên Sheets?
2. Có cần filter/sort không?
3. Số cột / tần suất sửa?
4. Bảng có phải nguồn sự thật pháp lý/giá không? (nếu có → CSV + quyền truy cập, không public MD)
5. Nếu chỉ cần hiển thị ngắn → generate MD từ vùng chọn

---

Case study

Startup B2B (HCM): README từng nhét bảng 25 cột ma trận module. Onboarding junior mở GitHub trên điện thoại không đọc nổi; mỗi đổi giá tạo PR conflict. Họ chuyển modules.csv làm nguồn, README chỉ còn bảng 6 module “hay hỏi”, generate bằng tool khi release. Thời gian review PR bảng giảm rõ — reviewer chỉ diff vài hàng MD.

Freelancer docs API: khách gửi CSV endpoint. Trong repo giữ endpoints.csv; trong README.md chỉ bảng Method × Path × Auth (4 cột) convert từ CSV. Khi thêm endpoint: sửa CSV trước, rồi regenerate đoạn MD — không sửa pipe tay.

---

Tóm tắt một dòng

Docs để đọc → Markdown table. Dữ liệu để sống → CSV. Dùng generator khi đã quyết định cần pipe table; đừng dùng generator như lý do để nhồi cả sheet vào README.

---

Liên kết liên quan

• Tạo bảng Markdown — CSV/Excel → bảng MD
• Cách dùng markdown table generator — lỗi lệch cột & quy trình paste
• Bảng Markdown GitHub vs Notion — tương thích platform
• JSON ↔ CSV — khi dữ liệu là JSON API
• Danh sách công cụ