Bảng Markdown GitHub README vs Notion | Alignment, escape dấu | và khi nào dùng CSV

(Cập nhật: 19 tháng 7, 2026 ) Markdown GitHub Notion bảng Markdown README CSV
Kết luận

Bảng GitHub README và bảng Notion không phải cùng một “Markdown table”. GFM cần header + hàng --- + số cột khớp; Notion paste thêm điều kiện không lệch pipe và escape |. Căn lề (:---) hữu ích trên GitHub; Notion có thể bỏ qua. Bảng lớn hoặc cần tính toán → CSV, không nhồi README.

Dev và PM ở Việt Nam thường viết spec trên Notion, rồi copy sang README GitHub cho team outsource — hoặc ngược lại: bảng trong PR được paste vào wiki Notion cho non-dev. Một trong hai nơi bảng “đẹp”, nơi kia cột trôi. Nguyên nhân gần như luôn là số | lệch, thiếu hàng separator, hoặc dấu | trong cell (version, OR logic, tiếng Việt ít gặp hơn tiếng Anh kỹ thuật).

Bài này so sánh hành vi GitHub vs Notion, hướng dẫn alignment / escape, và khi nào đừng dùng table — hãy CSV. Generator: Tạo bảng Markdown.

Cấu trúc tối thiểu (dùng chung được)

| Tính năng | Free | Pro |
| --------- | ---- | --- |
| SSO       | No   | Yes |
| Audit log | No   | Yes |

Ba thành phần bắt buộc:

  1. Hàng header — tên cột
  2. Hàng separator — chỉ - và | (có thể thêm : để căn)
  3. Hàng dữ liệu — cùng số cột với header

Thiếu separator → nhiều parser không nhận là table (GitHub sẽ ra đoạn text thường).

GitHub README vs paste Notion

Hành vi bảng Markdown
Tiêu chí GitHub (GFM) Notion (paste MD)
Separator \|---\| Bắt buộc để render table Cần có; thiếu dễ thành text
Alignment :--- Hỗ trợ trái/giữa/phải Thường mất sau khi thành Notion table
Số cột lệch Cột trống / lệch rõ Dễ vỡ cả block
\| trong cell Cần \\| Rất dễ cắt cột nếu quên escape
Ô trống \| \| vẫn tính cột Nên giữ đủ \| kể cả ô trống
Bảng rất rộng Scroll ngang trên web Nên chuyển Database hoặc CSV import

Workflow khuyến nghị cho team VN

  1. Soạn nguồn trong Sheets (dễ chỉnh cột)
  2. Generate Markdown bằng tool (alignment + pipe đều)
  3. Preview GitHub trước (PR draft)
  4. Paste Notion sau — nếu Notion lệch, sửa source MD chứ đừng sửa tay từng ô trên hai nơi

Tránh maintain hai bản “bảng sự thật” — một CSV/Sheets + một artifact Markdown generate lại khi cần.

Alignment: khi nào đáng dùng

| API        | Latency | QPS |
| :--------- | ------: | --: |
| /v1/users  | 120ms   | 800 |
| /v1/orders | 40ms    | 1200 |
  • :--- trái — tên, mô tả
  • :---: giữa — status ngắn (OK / FAIL)
  • ---: phải — số, tiền, %

Trên GitHub README, alignment giúp scan số liệu. Trên Notion, sau paste thường thành table native — alignment Markdown có thể không còn ý nghĩa; khi đó căn trong UI Notion.

Đừng tin “căn bằng cách thêm space trong cell” — GFM không căn theo khoảng trắng source; chỉ hàng separator quyết định.

Escape dấu | và lỗi vỡ cột

Ví dụ hỏng

| Rule | Expression |
| ---- | ---------- |
| OR   | a|b|c      |

Parser thấy quá nhiều | → cột thừa.

Cách sửa

| Rule | Expression |
| ---- | ---------- |
| OR   | a\\|b\\|c  |

Hoặc viết a OR b OR c / a / b / c nếu không cần ký tự pipe.

Lỗi khác hay gặp

Triệu chứngNguyên nhânSửa
Không thành bảngThiếu hàng --- ngay dưới headerThêm separator
Cột cuối “dính”Thiếu | cuối hàngMỗi hàng cùng pattern | … |
Lệch một hàngCopy từ Word/Docs mang ký tự lạGenerate lại từ tool
Tab thay spacePaste từ IDENormalize bằng generator

Tiếng Việt trong cell (Đà Nẵng, giá) không phải vấn đề encoding nếu file UTF-8 — vấn đề là pipe và số cột.

Dùng Markdown Table Generator thế nào

Công cụ Kawa nhận dữ liệu kiểu Excel/CSV (paste), cho chọn căn trái / giữa / phải, rồi copy Markdown. Phù hợp khi:

  • README so sánh gói Free/Pro/Enterprise
  • Bảng endpoint trong docs nội bộ
  • Ma trận quyền role × action

Chạy trên trình duyệt — paste spec nội bộ không cần upload server. Sau khi copy: mở preview GitHub + paste Notion một lần như checklist trên.

Khi nào dùng CSV thay table Markdown

Giữ Markdown table khi:

  • ≤ ~8–10 cột, ≤ ~30 hàng
  • Đọc trong diff Git / PR review
  • So sánh feature định tính (Yes/No)

Chuyển CSV (hoặc Sheets) khi:

  • Hơn ~15 cột (mobile README không đọc nổi)
  • Cần filter/sort bởi PM không rành Git
  • Import Notion Database (CSV/API tốt hơn paste MD)
  • Pipeline script (Node đọc CSV → generate docs)
  • Có công thức / số liệu tài chính

Mẫu quyết định nhanh:

README “so sánh 4 gói × 6 tính năng” → Markdown table
Bảng giá 40 SKU × 12 cột thuế → CSV + link Sheets
Changelog endpoint → Markdown table ngắn
Dump analytics 500 hàng → CSV, không nhét README

Có thể giữ cả hai: CSV trong /data, README chỉ embed 5 hàng nổi bật + link “full table”.

Case study: bàn giao cho team outsource

Agency tại Hà Nội viết API docs trong Notion. Freelancer BE chỉ clone GitHub — không vào workspace Notion. PM copy bảng “Error code” sang docs/errors.md.

Lần 1: Copy tay từ Notion → thiếu separator → GitHub hiện tường chữ.
Lần 2: Export CSV từ Notion database → dán generator → README Pass; khi Notion cập nhật mã lỗi mới, regenerate từ CSV thay vì sửa MD tay.

Thời gian sync giảm vì một nguồn (CSV/Database) và hai output.

Checklist trước khi merge README

  • Có hàng |---| ngay dưới header
  • Mọi hàng cùng số cột
  • \| trong nội dung đã \\|
  • Preview GitHub OK trên mobile web
  • Nếu cần Notion: paste thử trang trống
  • Bảng > 10 cột: cân nhắc CSV + link

Liên kết hữu ích

Tóm lại: GitHub cần cú pháp GFM đủ cột; Notion cần pipe sạch và escape. Alignment giúp README; CSV cứu dữ liệu lớn. Generate một lần, preview hai nơi — đừng maintain hai bảng tay song song.