Markdown là gì? Heading và list trước khi học cheat sheet【2026】

Sinh viên IT, freelancer outsource và junior ở Việt Nam thường search “Markdown là gì” sau khi mentor bảo “viết README bằng Markdown” hoặc khách Nhật gửi file .md. Mở cheat sheet 50 dòng ngay lúc đó dễ nhớ cú pháp nhưng không biết cấu trúc — README thành một khối bullet loạn, không có heading, hoặc heading không hiện vì thiếu khoảng trắng.

Bài này không thay cheat sheet Markdown GitHub. Mục tiêu: hiểu Markdown là gì, vì sao heading + list là nền, rồi mới tra cú pháp còn lại khi cần.

Ai nên đọc bài này

• Mới clone repo lần đầu và thấy README.md
• Viết báo cáo lab / tài liệu API ngắn trên HackMD
• Nhận file .md từ khách và bị “heading không lên” trên GitHub
• Biết HTML nhưng chưa quen workflow docs-as-code

---

Markdown là gì (định nghĩa dùng được)

Markdown là markup nhẹ: bạn gõ text thuần, thêm ký hiệu tối thiểu, công cụ render thành HTML.

Bạn viết:          GitHub hiện:
# Tên dự án   →    tiêu đề lớn (H1)
## Cài đặt    →    mục lục / section
- Node 20     →    bullet
1. Clone      →    bước có số

Khác HTML: bạn không phải đóng thẻ. File vẫn đọc được trong Notepad nếu render hỏng. Đó là lý do README, PR description, issue GitHub, và nhiều wiki nội bộ chọn Markdown.

Markdown ≠ “app ghi chú”

Notion / Obsidian / Typora là ứng dụng; Markdown là cú pháp bên trong. Cùng một file .md có thể mở ở VS Code, GitHub web, HackMD — render hơi khác dialect, nhưng heading và list gần như phổ quát.

Ba nơi bạn gặp Markdown mỗi tuần

Nơi	Việc thường làm	Heading / list dùng thế nào
GitHub README	Mặt tiền repo cho khách / reviewer	# tên dự án, ## Install / Usage
HackMD / GitLab wiki	Biên bản họp, spec ngắn	## theo agenda; 1. action item
PR / issue	Mô tả thay đổi	List checklist - [ ]; ít khi cần bảng

---

Vì sao bắt đầu bằng heading và list

Cheat sheet thường liệt kê 8–12 ký hiệu cùng lúc. Thực tế sprint / đồ án:

1. Người đọc cần biết đang ở section nào → heading
2. Người đọc cần scan bước hoặc bullet → list
3. Link, ảnh, bảng, checkbox chỉ hữu ích sau khi xương sống đã đúng

Nếu chỉ có list không heading, README dài 80 dòng trở thành tường chữ trên mobile. Nếu chỉ có heading không list, “Cài đặt” thành đoạn văn khó làm theo.

---

Heading — tạo khung tài liệu

Cú pháp tối thiểu

# Tên dự án (H1 — chỉ một cái trong README)

## Cài đặt (H2 — section chính)

### Yêu cầu hệ thống (H3 — chi tiết trong section)

Quy tắc thực dụng:

• README GitHub: một # (tên repo / sản phẩm)
• Mọi mục lớn (Install, Usage, API, License) = ##
• Chi tiết trong mục = ### — tránh xuống #### trừ khi tài liệu rất dài
• Bắt buộc một space half-width sau #

Sai phổ biến (đặc biệt với Unikey / paste)

##Cài đặt          ❌ thiếu space → không thành heading
＃ Cài đặt         ❌ ＃ full-width → GitHub bỏ qua
##  Cài đặt        ⚠️ nhiều space vẫn thường render, nhưng formatter sẽ chuẩn hóa
# Tiêu đề
# Tiêu đề khác     ❌ hai H1 — mục lục và SEO docs rối

Case: Freelancer paste spec từ Word tiếng Việt sang README.md. Unikey để chế độ full-width cho dấu câu; vài dòng # thành ＃. Local Typora vẫn “đẹp” vì app khoan dung; github.com thì section biến thành paragraph thường — khách bảo “file hỏng”.

Cách xử lý: dán vào Markdown Formatter → Format (full-width → half-width, ##text → ## text) → copy lại → Preview trên GitHub.

Mẫu khung README 30 giây

# shop-api

API đơn hàng cho client mobile.

## Yêu cầu

- Node.js 20+
- PostgreSQL 15

## Cài đặt

1. Clone repo
2. Copy `.env.example` → `.env`
3. Chạy `npm install` rồi `npm run migrate`

## Sử dụng

Xem [docs/api.md](./docs/api.md).

## License

MIT

Chỉ heading + list (+ một link). Đủ để mentor / khách hiểu cách chạy. Chi tiết cú pháp link và code: cheat sheet.

---

List — bullet và bước có thứ tự

Bullet (thứ tự không quan trọng)

- Express
- Prisma
- Zod

Dùng cho dependency, feature, “đã làm / chưa làm” mức cao. Có thể dùng * hoặc + — team nên thống nhất một ký hiệu (thường -).

Numbered (thứ tự bắt buộc)

1. Backup database
2. Chạy migration
3. Restart worker

Đánh số 1. 1. 1. cũng được nhiều renderer tự tăng — nhưng viết 1. 2. 3. rõ hơn khi review diff.

Lồng list (indent)

- Backend
  - API
  - Worker
- Frontend
  1. Cài pnpm
  2. Chạy `pnpm dev`

Indent bằng 2 hoặc 4 space half-width (không tab lẫn space bừa). Full-width space đầu dòng từ Word hay phá nest — Formatter của Kawa chuẩn hóa indent list về half-width.

Checklist GitHub (học sau, nhưng hay gặp)

- [ ] Viết test
- [x] Update README

Cần space trong ngoặc. Dùng trong PR; không thay Jira cho team lớn.

---

Mini case study: báo cáo lab bị “một khối chữ”

Trước (sai):

Đồ án giữa kỳ API bán hàng
Clone về rồi npm install cấu hình env chạy migrate
Lưu ý dùng Node 20 không dùng 18
Endpoint nằm trong thư mục routes

Mentor phải đọc tuần tự, không nhảy mục.

Sau (heading + list):

# Đồ án giữa kỳ — API bán hàng

## Môi trường

- Node.js 20 (không dùng 18)
- npm 10+

## Chạy local

1. `git clone …`
2. `cp .env.example .env`
3. `npm install`
4. `npm run migrate`
5. `npm run dev`

## Cấu trúc

- `routes/` — endpoint HTTP
- `services/` — business logic

Cùng nội dung, scan được trên điện thoại trong 20 giây. Đó là giá trị Markdown — không phải “biết nhiều ký hiệu”.

---

Quy trình 5 phút khi nhận file .md lệch

1. Mở file trong VS Code, bật preview
2. Kiểm tra từng dòng heading: có space sau #? có ＃ full-width không?
3. Kiểm tra list: -item → sửa thành - item
4. Nếu file dài / paste từ Notion: mở Markdown Formatter, Format một lần (giữ code block)
5. Push branch → xem Preview trên GitHub (nguồn sự thật cho README)

Công cụ format chạy local trên trình duyệt — phù hợp tài liệu nội bộ / token trong ví dụ (không dán lên site lạ).

---

Khi nào chuyển sang cheat sheet đầy đủ

Đọc tiếp Markdown cheat sheet GitHub README khi bạn cần:

• Link tương đối và ảnh demo không 404
• Code block có language tag (highlight)
• Bảng so sánh feature
• Checkbox task list chi tiết trong PR

Bài hiện tại cố ý dừng ở heading + list để bạn có xương sống trước khi nhồi cú pháp.

---

FAQ nhanh trong team chat

Câu hỏi	Trả lời một câu
Markdown khác HTML?	Ít thẻ hơn, đọc được khi chưa render
Học gì trước?	# heading rồi - / 1. list
Heading không lên?	Thiếu space hoặc dùng # full-width
Tool nào dọn paste?	Markdown Formatter Kawa

Bookmark lý do: giải thích “Markdown là gì” + mẫu README tối thiểu bằng heading/list — gửi cho junior trước khi bảo họ học cả cheat sheet.