Markdown cheat sheet GitHub README | Heading, link, code, table copy-paste【2026】

Freelancer, sinh viên và team outsource ở Việt Nam thường giao repo “code chạy được nhưng README đọc không nổi”: khách mở GitHub trên điện thoại thấy một khối chữ, ảnh demo 404, hoặc bảng feature lệch cột. Hầu hết không phải lỗi Git — mà là cú pháp Markdown / GitHub Flavored Markdown (GFM) viết sai vài ký tự.

Markdown là markup nhẹ: bạn viết plain text có ký hiệu (#, [](), ```, |), GitHub render thành heading, link, code highlight và bảng. README là mặt tiền repo — reviewer và khách hàng nhìn đó trước khi clone. Cheat sheet này tập trung bốn khối dùng mỗi ngày (heading / link / code / table), kèm list, checkbox và lỗi thực tế khi paste từ Notion, Word hoặc IME tiếng Việt.

Không cố cover mọi dialect (CommonMark vs Obsidian vs Typora). Mục tiêu: mở file README, copy đúng mẫu, preview trên github.com, merge được.

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

• Tra cứu nhanh 8 ký hiệu Markdown hay dùng trong README
• Xây cấu trúc heading rõ (một H1, section bằng H2) để mục lục GitHub hiện đúng
• Viết link và ảnh relative không chết khi xem trên web
• Bọc lệnh / snippet trong code block có language tag để highlight
• Làm bảng ngắn đủ đọc + biết khi nào chuyển sang bài chuyên về table
• Chạy checklist lỗi trước khi mở PR, và dọn spacing bằng tool local

---

Cheat sheet nhanh (copy theo cột trái)

Khi đang viết README giữa PR, bạn không cần nhớ lý thuyết — cần cú pháp đúng + lúc nào dùng. Bảng dưới là bản tra cứu ghim bookmark.

Phần còn lại giải thích từng khối, kèm mẫu sai thường gặp trên repo outsource và bài tập nhỏ bạn có thể sửa ngay trên branch hiện tại.

---

Heading — xương sống README

Heading quyết định người đọc scan được gì trong 10 giây. Trên GitHub, sidebar mục lục và jump-to-heading dựa vào # / ## / ###. Nếu bạn dùng **Cài đặt** in đậm thay vì ## Cài đặt, mục lục trống — khách phải kéo cả trang.

# Tên dự án

Một câu mô tả sản phẩm làm gì.

## Cài đặt
## Cách dùng
## API
## License

Quy ước thực dụng cho team VN / outsource:

Quy tắc	Lý do
Một # (H1) duy nhất	Trùng H1 làm mục lục / SEO repo rối; README dài càng loạn
Section chính dùng ##	Người đọc scan nhanh trên mobile GitHub (nhiều PM chỉ xem trên phone)
Luôn ## (có space)	##Cài đặt không thành heading — vẫn là text thường
Half-width #	Full-width ＃ từ IME → GitHub không parse

Sai mẫu hay gặp khi paste từ Word, Google Docs, hoặc gõ bằng bộ gõ có full-width:

##Cài đặt          ← thiếu space
＃ Cách dùng       ← full-width #
# Tên
# Tên khác         ← hai H1

Cách sửa nhanh: tìm mọi dòng bắt đầu bằng # trong README, đảm bảo sau dấu # là space ASCII. Nếu file đã trộn full-width và thiếu spacing hàng loạt, dán vào Markdown Formatter — tool chuẩn hóa # half-width và khoảng trắng heading/list, giữ nguyên code block, xử lý trên trình duyệt (không upload server). Sau đó diff lại trước khi commit.

Gợi ý cấu trúc tối thiểu cho repo giao khách: H1 tên sản phẩm → đoạn mô tả 2–3 câu → ## Cài đặt → ## Cách dùng → ## Cấu hình (env) → ## License hoặc ## Liên hệ. Đừng nhồi changelog dài vào README; để CHANGELOG.md hoặc Releases.

---

List và checkbox

List giúp bước onboarding không bị “đoạn văn một cục”. Freelancer hay viết “clone rồi npm install rồi tạo env rồi chạy” trong một câu — khách bỏ sót bước. Tách bullet rõ hơn.

- Clone repo
- Cài dependency
- Chạy dev server

1. Tạo `.env`
2. Điền `API_KEY`
3. Restart

- [x] Viết README
- [ ] Thêm screenshot
- [ ] Publish npm

Bullet (- hoặc *) cho danh sách không thứ tự (dependency, tính năng). Đánh số 1. khi thứ tự bắt buộc (onboarding, migration). Nested list được GFM hỗ trợ nếu thụt đúng bằng space — đừng trộn tab lung tung giữa Windows và macOS trong cùng file.

Checkbox (- [ ] / - [x]) chỉ tin cậy trên GitHub Flavored Markdown: README, issue, PR description. HackMD và Notion có thể render khác hoặc chuyển thành block riêng. Dùng checkbox cho “việc còn lại trước khi handover”; đừng biến README thành board thay Jira/Linear khi team > 5 người — sẽ stale rất nhanh.

Lỗi nhỏ nhưng hay gặp: - [x]done thiếu space sau ] hoặc viết - [X] (một số renderer chấp nhận, nên thống nhất chữ x thường).

---

Link và ảnh (điểm chết README nhiều nhất)

Trên preview local (VS Code Markdown preview) ảnh vẫn hiện vì path resolve theo workspace; lên github.com thì path tính từ thư mục chứa file .md. Đó là lý do “máy tôi thấy ảnh, khách báo vỡ”.

[Tài liệu API](./docs/api.md)
[Demo live](https://example.com)
![Screenshot trang chủ](./assets/home.png)

Ví dụ: README ở root repo, ảnh nằm docs/img/demo.png:

![Demo](./docs/img/demo.png)

Nếu bạn viết docs trong docs/guide.md và muốn trỏ ảnh cùng thư mục docs/img/, path từ guide.md sẽ là ./img/demo.png — không copy nguyên path của README. Mỗi file Markdown có “gốc” riêng.

Sai phổ biến trong team outsource:

• Dán path Windows tuyệt đối (C:\Users\...) hoặc file:/// — chết 100% trên GitHub
• git mv đổi assets/ → static/ nhưng quên search-replace trong *.md
• Link tới branch private hoặc wiki nội bộ mà khách không có quyền — click ra 404/403
• Dùng raw.githubusercontent.com hardcode commit cũ; ảnh OK một thời gian rồi lệch với UI mới

Alt text trong ![alt](...) nên mô tả ngắn (ví dụ “Form đăng nhập sau khi SSO”). Khi ảnh fail, độc giả và screen reader vẫn hiểu ý. Tránh alt rỗng ![](...) cho screenshot quan trọng.

Link issue/PR: trong cùng repo có thể dùng #12; khi README được fork hoặc mirror, full URL https://github.com/org/repo/issues/12 ổn định hơn. Badge (build, coverage) cũng là ảnh Markdown — kiểm tra URL badge trên mạng công ty / VPN khách.

---

Code — inline và fenced block

Hai tầng: inline cho tên lệnh trong câu, fenced block cho đoạn copy-paste. README chỉ screenshot terminal mà không có block text khiến khách phải gõ lại — dễ typo npm thành nmp.

Inline:

Chạy `npm install` rồi `npm run dev`.

Khối nhiều dòng — thêm language tag ngay sau fence mở để GitHub highlight:

```bash
npm install
npm run build
```

```ts
export function greet(name: string) {
  return `Hello, ${name}`;
}
```

Lưu ý GFM thực dụng:

• Fence ``` phải ở đầu dòng. Thụt 2–4 space trước fence có thể khiến parser hiểu khác hoặc nuốt highlight
• Đóng fence bằng ba backtick trên dòng riêng; thiếu dòng đóng → phần README phía dưới bị “nuốt” vào code
• Language hay dùng: bash, js, ts, json, yaml, sql, python, dockerfile
• Ví dụ lệnh cài đặt nên là bash (hoặc sh) thay vì liệt kê dài trong bullet — khách bấm copy một lần
• Không paste token production, private key, connection string thật vào block “ví dụ”; dùng placeholder YOUR_API_KEY

Muốn hiện backtick trong inline code: bọc bằng hai backtick bên ngoài theo quy ước GFM, hoặc diễn đạt lại câu để khỏi nest. Đừng copy code từ Slack/Teams rồi để smart quote (' cong) — parser và shell đều có thể lỗi; giữ ASCII quote trong fence.

Khi README song ngữ (VI + EN) cho khách Nhật/Hàn qua middleman VN: giữ một block lệnh chuẩn, mô tả bằng hai đoạn prose — tránh hai block lệnh lệch version.

---

Bảng — đủ dùng trong README

Bảng phù hợp ma trận ngắn: môi trường, feature Free/Pro, browser support. Không nhồi 20 cột spec vào README — khó đọc trên mobile và dễ vỡ pipe.

| Env    | Port | Ghi chú        |
| ------ | ---- | -------------- |
| local  | 3000 | Hot reload     |
| staging| 8080 | Auth bắt buộc  |

Ba thành phần bắt buộc: hàng header, hàng separator (|---|---|), hàng dữ liệu với cùng số cột (cùng số |). Thiếu separator → GitHub in plain text, không thành table.

Căn cột GFM: :--- trái, :---: giữa, ---: phải. Ô có dấu | (ví dụ ghi status|draft) phải escape \|, không thì cột bị cắt từ đó. Ô trống vẫn cần giữ | đủ — đừng “dọn đẹp” bằng cách xóa pipe.

Phạm vi cheat sheet này: đủ để README không vỡ. Alignment sâu, paste Notion lệch cột, khi nào dùng CSV: đọc Bảng Markdown GitHub vs Notion. Cần generate nhanh từ dữ liệu sẵn: Tạo bảng Markdown.

---

Nhấn mạnh, quote, đường kẻ

**Quan trọng:** không commit file `.env`.

*Optional* nếu bạn dùng Docker.

~~API cũ~~ — đã deprecate ở v2.

> Lưu ý: node ≥ 20.

---

Dùng **đậm** cho cảnh báo bảo mật, breaking change, hoặc điều kiện tiên quyết (phiên bản Node). Tránh bold cả đoạn văn — mất tín hiệu. *nghiêng* cho thuật ngữ lần đầu hoặc ghi chú phụ. Gạch ngang ~~~~ khi đánh dấu API cũ vẫn nhắc để người upgrade biết.

Quote (>) hợp ghi chú môi trường hoặc trích message lỗi mẫu; không dùng quote thay heading. Đường kẻ --- tách phần “Tài liệu liên quan” cuối README dài — nếu cứ chèn giữa mọi section, trang sẽ đầy đường kẻ vô nghĩa.

---

Case study ngắn

1) Freelancer giao repo cho khách chỉ xem mobile

Khách báo “README khó đọc”. File dùng **Cài đặt**, **Chạy**, **Deploy** thay vì ##. Trên điện thoại không có mục lục hữu ích. Sửa bốn dòng thành heading H2 → GitHub hiện outline; khách tự làm theo ## Cài đặt mà không cần call thêm.

2) Team outsource dán từ Notion sang GitHub

Spec viết trên Notion, export/paste vào README: heading thành text, list dính đoạn, bảng lệch. Notion không phải GFM thuần. Cách làm việc ổn định: giữ nội dung ý, viết lại heading/list/link bằng cú pháp trong cheat sheet; hoặc dán qua Markdown Formatter để sửa spacing/full-width rồi preview trên PR. Đừng expect “Paste đặc biệt” một lần là xong.

3) Ảnh demo 404 sau reorganize thư mục

PR “gọn structure” git mv assets media. Diff code sạch, README vẫn ![...](./assets/...). Reviewer desktop có cache local; khách clone mới thấy ảnh chết. Checklist bắt buộc: sau mọi git mv ảnh/docs, rg (hoặc search IDE) path cũ trong *.md.

4) Code block không đóng fence

Thiếu ``` đóng khiến nửa dưới README (license, contact) nằm trong khối code xám. Triệu chứng: “từ đoạn Install trở đi toàn monospace”. Mở raw file, đếm số fence mở/đóng phải chẵn.

---

Checklist trước khi merge README

In và tick trước khi bấm merge — đặc biệt khi handover cho khách không rành Git:

1. Đúng một H1; mọi section chính là ## (space ASCII, half-width #)
2. Click thử mọi ](...) và ![](...) trên github.com (incognito), không chỉ preview local
3. Lệnh cài/chạy nằm trong ```bash (hoặc tương đương), không chỉ screenshot
4. Bảng có separator, số | đều mỗi hàng; bảng quá rộng → rút cột hoặc CSV/docs riêng
5. Không có secret/token/production URL nhạy cảm trong fence “ví dụ”
6. Mở tab Preview trên GitHub hoặc xem file trong PR trên web trước khi merge
7. Nếu vừa format hàng loạt: đọc diff — đảm bảo code block không bị tool (hoặc tay) phá fence

---

Cách dùng Markdown Formatter (Kawa)

Khi README lệch vì paste IME, full-width #, hoặc ##text thiếu space:

1. Mở Markdown Formatter
2. Dán toàn bộ hoặc đoạn heading/list đang lỗi
3. Chạy Format — chuẩn hóa half-width và khoảng trắng; code block được giữ
4. Copy lại vào repo, tạo PR nhỏ “docs: normalize markdown spacing”, preview trên GitHub

Tool chạy trên trình duyệt, phù hợp README nội bộ chưa public hoặc đoạn có mô tả luồng nghiệp vụ nhạy cảm hơn việc dán lên formatter online lạ. Nó không thay bạn viết nội dung — chỉ giảm lỗi cơ học trước khi reviewer soi ý.

---

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

Heading GitHub README viết thế nào?
# một lần cho tên dự án, ## cho từng section. Luôn có space sau #. Full-width hoặc dính chữ (##Cài) = không ra heading.

Làm sao để code block được highlight?
Mở bằng ba backtick + language (bash, ts…), đóng bằng ba backtick dòng riêng, fence sát lề trái.

Link/ảnh tương đối tính từ đâu?
Từ thư mục chứa file Markdown đó. README root dùng ./docs/...; file trong docs/ dùng path khác. Path ổ C:\ chắc chắn chết trên GitHub.

Bảng tối thiểu cần gì?
Header + hàng |---| + data cùng số cột. Chi tiết alignment / Notion / CSV: bài bảng GitHub vs Notion.

Có cần học hết Markdown không?
Không. Với README, thành thạo bốn khối heading–link–code–table (+ list) là đủ 90% việc hàng ngày. Phần còn lại tra cheat sheet này khi cần.

---

Liên kết liên quan

• Markdown Formatter — chuẩn hóa spacing / half-width, giữ code block
• Tạo bảng Markdown
• Bảng Markdown GitHub vs Notion
• Danh sách công cụ