Hướng dẫn cú pháp ảnh Markdown 2026: GitHub, Notion, HackMD, Obsidian
Lười đọc dài? Ba câu tổng hợp
- Cú pháp ảnh Markdown cơ bản là
, mọi platform đều hỗ trợ - Cách điều chỉnh kích thước ảnh mỗi platform khác nhau — đây là cái bẫy lớn nhất
- Ảnh phải là "direct link công khai truy cập được", không thể dùng link chia sẻ Google Drive
OK, tiếp theo là cheatsheet đầy đủ.
Cú pháp cơ bản: chạy trên mọi platform
alt text: chữ hiển thị khi ảnh không load được, cũng là nội dung screen reader đọcimage URL: phải là URL truy cập trực tiếp được (direct link)
Thêm title (hiện khi hover):
Cú pháp reference (phù hợp khi dùng lặp một ảnh):
![alt text][logo]
[logo]: https://example.com/image.png "Title"
Cách điều chỉnh kích thước trên từng platform
Đây là chỗ dễ mắc bẫy nhất. Dựa trên test thực tế 5 platform phổ biến, mỗi nơi làm mỗi kiểu.
| Platform | Cú pháp điều chỉnh size | Ví dụ |
|---|---|---|
| GitHub | Không hỗ trợ Markdown, phải dùng HTML | <img src="url" width="300"> |
| HackMD | Thêm =width×height sau URL |
 |
| Notion | Kéo thả chỉnh, không có cú pháp | Upload rồi kéo cạnh |
| Obsidian | Thêm ` | widthhoặc |
| Typora | Dùng HTML hoặc zoom markup | <img src="url" style="zoom:50%"> |
GitHub
Markdown renderer của GitHub không hỗ trợ bất kỳ cú pháp chỉnh size ảnh nào. Cách duy nhất là HTML:
<img src="https://example.com/image.png" width="400" alt="mô tả">
GitHub hỗ trợ thuộc tính width, height, align trên thẻ <img>, nhưng không hỗ trợ style (lọc đi vì bảo mật).
HackMD
HackMD dùng cú pháp mở rộng riêng, thêm =width×height sau URL:
Chỉ định width, height tự co giãn:
Cú pháp này chỉ HackMD mới có, platform khác không hoạt động.
Obsidian
Cú pháp size ảnh của Obsidian đặt trong alt text:
Obsidian còn hỗ trợ wiki-style internal link:
![[image.png|300]]
Notion
Notion import Markdown hỗ trợ cú pháp ảnh cơ bản, nhưng chỉnh size chỉ bằng chuột kéo thả trong UI Notion. Không có cú pháp control.
Lưu ý thêm: Notion sẽ tự re-upload ảnh ngoài lên CDN riêng (prod-files-secure.s3.us-west-2.amazonaws.com), nên source ảnh không ảnh hưởng tốc độ hiển thị, nhưng cũng đồng nghĩa bạn không update được version trên Notion qua update ảnh gốc.
Hỗ trợ nguồn ảnh trên từng platform
Không phải URL ảnh nào cũng hiển thị đúng trên mọi platform. Kết quả test:
| Nguồn ảnh | GitHub | HackMD | Notion | Obsidian | Typora |
|---|---|---|---|---|---|
| Image host direct link (lpic.cc, ImgBB...) | OK | OK | OK | OK | OK |
| Ảnh trong repo GitHub | OK | OK | OK | Cần setting | OK |
| Google Drive share link | Không hiển thị | Không hiển thị | Tự re-upload | Không ổn định | Không hiển thị |
| Dropbox share link | Không hiển thị | Không hiển thị | Tự re-upload | Không ổn định | Không hiển thị |
| Base64 inline | Có | Có | Không | Có | Có |
Điểm quan trọng: link chia sẻ Google Drive và Dropbox không phải direct link ảnh, đa số Markdown platform không render được. Để nhúng ảnh trong Markdown, bạn cần dịch vụ image hosting cung cấp "direct link".
Chính sách Hotlinking: ảnh của bạn có bị chặn không?
Hotlinking là dùng ảnh từ server khác trong trang của mình. Một số dịch vụ chặn hotlinking để tiết kiệm băng thông.
| Dịch vụ | Cho hotlink? | Ghi chú |
|---|---|---|
| Image host (lpic.cc, ImgBB v.v.) | Có | Là chức năng cốt lõi |
| GitHub repo | Có (có giới hạn) | Traffic cao có thể bị throttle |
| Imgur | Một phần | Một số quốc gia bị hạn chế |
| WordPress.com | Không | Kiểm tra Referer |
| Đa số website | Không | Thường chặn reference ngoài |
Best practice cho viết tài liệu kỹ thuật
Vài nguyên tắc khi viết technical doc hay blog:
Alt text không được lười
<!-- Không đạt -->
<!-- Đạt -->
Chức năng của alt text:
- Hiển thị khi ảnh load lỗi
- Screen reader đọc cho người khiếm thị (accessibility)
- Search engine hiểu nội dung ảnh (SEO)
Đặt tên file ảnh
<!-- Không đạt -->
Screenshot 2026-03-15 at 14.32.05.png
IMG_4521.jpg
<!-- Đạt -->
github-actions-workflow-config.png
npm-install-success-output.png
Tên tốt giúp 6 tháng sau vẫn biết ảnh này là gì.
Chọn format ảnh
- Screenshot, UI: PNG (chữ sắc không mờ)
- Ảnh chụp, hình phức tạp: WebP hoặc JPEG (dung lượng nhỏ hơn)
- Icon, Logo, biểu đồ: SVG (zoom không vỡ)
- Demo thao tác động: GIF hoặc WebP animation (giữ dưới 5MB)
Nén trước khi upload
Dùng format gì cũng nên nén trước khi upload. Công cụ đề xuất:
- Squoosh (squoosh.app) — do Google làm, xử lý ngay trên trình duyệt
- TinyPNG (tinypng.com) — nén hàng loạt PNG/JPEG
- ImageOptim (macOS) — kéo thả là nén, giữ chất lượng
Cách viết tương thích cross-platform
Nếu tài liệu Markdown của bạn cần hiển thị đúng trên nhiều platform, dùng chiến lược:
- Cú pháp ảnh: dùng standard
, không dùng cú pháp chỉnh size đặc thù platform - Kích thước: chỉnh trước khi upload (khuyến nghị rộng 600–800px), không dựa vào cú pháp
- Nguồn ảnh: dùng image host direct link (ví dụ lpic.cc cho upload không cần đăng ký và direct link), không dùng Google Drive hay Dropbox share link
- Format: PNG hoặc WebP, tránh BMP hay TIFF
Lưu ý: lpic.cc hiện không hỗ trợ custom image size hay crop realtime, cần xử lý ảnh xong trước khi upload. Cần API batch upload hay xử lý động, cân nhắc Cloudinary hoặc dịch vụ tương tự.
Kịch bản đặc thù cho developer Việt Nam
Một số tình huống thực tế ở cộng đồng dev Việt Nam:
Viết documentation cho open-source project
Viết README.md hoặc tài liệu cho repo GitHub — đây là nơi Markdown phát huy mạnh nhất. Khuyến nghị:
- Ảnh demo/screenshot: upload trực tiếp trong repo (thư mục
docs/images/) để version control cùng code - Ảnh lớn ít thay đổi: upload lên image host bên ngoài (lpic.cc, Imgur) để không phình size repo
- Badge, shield.io: dùng URL động từ shields.io
Blog Dev.to, Hashnode, Medium cho dev Việt
Nhiều developer Việt Nam đăng blog song song trên các platform này. Chiến lược:
- Ảnh lưu trên image host trung tâm (lpic.cc là phù hợp) để cross-post một link dùng được khắp nơi
- Medium có quirk riêng: nó sẽ re-upload ảnh, nên link ngoài chỉ là "source", không phải bản được hiển thị
- Dev.to: cho paste direct URL, hoạt động tốt với mọi image host
Tài liệu nội bộ trên HackMD và Notion
- HackMD: dùng cho note cộng tác realtime, phù hợp cho team tech nội bộ
- Notion: phù hợp hơn cho documentation dài, wiki công ty
- Spiderum: cho bài blog kỹ thuật dài cho audience Việt
Zalo OA và Telegram channel
Telegram channel Việt Nam (nhóm dev, blockchain, gaming) đôi khi dùng Markdown trong tin nhắn. Chỉ hỗ trợ tập con nhỏ: bold, italic, inline code, link — không render ảnh từ Markdown syntax. Ảnh cần gửi trực tiếp dưới dạng file hoặc sticker.
Câu hỏi thường gặp (FAQ)
Q1: Markdown có căn giữa ảnh được không?
Standard Markdown không hỗ trợ căn ảnh. Trên GitHub có thể dùng HTML: <p align="center"><img src="url" width="400"></p>. HackMD hỗ trợ {:center}. Notion và Obsidian chỉnh qua UI.
Q2: Markdown dùng ảnh local được không?
Được, dùng relative path: . Nhưng chỉ hoạt động trong local editor (Typora, Obsidian, VS Code). Nếu publish lên web, phải upload ảnh lên image host lấy public URL.
Q3: Sao ảnh của mình không hiển thị trên GitHub README?
Ba lý do phổ biến nhất: (1) URL ảnh không phải direct link, là link cần login mới xem được; (2) Server chứa ảnh chặn hotlinking từ GitHub; (3) Relative path sai, không trỏ đúng vị trí trong repo.
Q4: Cú pháp size =300x của HackMD có chạy trên platform khác không?
Không. Cú pháp =width×height là mở rộng Markdown riêng của HackMD, không hoạt động trên GitHub, Notion, Obsidian. Nếu tài liệu cần cross-platform, chỉnh ảnh trước khi upload hoặc dùng thẻ HTML <img> (GitHub hỗ trợ, HackMD cũng hỗ trợ).
Q5: Direct link và share link khác nhau thế nào?
Direct Link là URL trỏ thẳng đến file ảnh, thường kết thúc bằng .jpg, .png, .webp. Trình duyệt mở ra chỉ thấy ảnh. Share link là URL webpage, mở ra thấy một trang web có chứa ảnh (ví dụ trang preview của Google Drive). Cú pháp ảnh Markdown cần direct link mới render đúng.
Q6: Làm blog kỹ thuật bằng tiếng Việt, nên chọn platform nào?
Tuỳ audience. Audience developer toàn cầu → Dev.to, Hashnode. Audience Việt Nam → Spiderum (support Markdown đầy đủ), Viblo (platform dev Việt Nam). Tech community Việt Nam đặc biệt thích Viblo cho bài technical deep-dive bằng tiếng Việt.
Q7: Ảnh code syntax highlight nên upload hay dùng code block?
Ưu tiên code block Markdown thật (```language) thay vì screenshot code:
- Code block cho phép copy, search, syntax highlight động
- Screenshot làm bài dài hơn, không accessibility-friendly
- Chỉ dùng screenshot khi cần show UI editor (ví dụ show breakpoint debug, IntelliJ feature)