Free Tools
Blog

Cách viết README bằng Markdown: bố cục, khối lệnh và xem trước

Admin Editor · 27/10/2026

Một README hữu ích giúp người khác hiểu dự án dùng để làm gì, cần chuẩn bị gì và chạy thử ra sao. Bạn không cần bắt đầu bằng một trang dài đầy huy hiệu: một tệp ngắn nhưng hướng dẫn đúng sẽ có ích hơn đoạn giới thiệu đẹp mà không có lệnh chạy.

Bài này đưa ra bố cục README cho một dự án nhỏ và cách xem trước bằng Markdown Previewer. Công cụ hiện có giao diện tiếng Anh; bạn vẫn có thể viết nội dung tiếng Việt và tải tệp Markdown hoặc HTML sau khi kiểm tra.

Bố cục README: mục đích dự án, cài đặt, chạy thử và giới hạn

README nên trả lời những câu hỏi nào?

Trước khi chọn định dạng, viết nháp câu trả lời cho năm câu hỏi:

  • Dự án giải quyết việc gì và dành cho ai?
  • Máy cần những phần mềm hoặc phiên bản nào?
  • Người mới cần chạy những lệnh nào, tại thư mục nào?
  • Đầu vào, đầu ra hoặc một ví dụ sử dụng là gì?
  • Hiện còn giới hạn gì cần biết?

Bạn có thể thêm ảnh, liên kết tài liệu, giấy phép hoặc cách đóng góp khi thực sự cần. Đừng ghi công nghệ hay khả năng chưa tồn tại chỉ để phần giới thiệu trông đầy đủ.

Bắt đầu với một khung đơn giản

Ví dụ dưới đây là mẫu minh họa, không phải lệnh cài đặt áp dụng cho mọi dự án:

# Tên dự án

Một câu mô tả việc dự án giúp người dùng thực hiện.

## Yêu cầu

- Phần mềm và phiên bản dự án đã kiểm tra
- Các dịch vụ cần có nếu dự án sử dụng

## Thiết lập

Ghi đúng thư mục cần mở và các bước cấu hình.

## Chạy thử

Ghi lệnh thực tế, cách mở ứng dụng và kết quả mong đợi.

## Giới hạn

Nêu phần đang thử nghiệm hoặc chưa được hỗ trợ.

Một tiêu đề cấp một cho tên dự án, rồi dùng cấp hai cho các phần chính, thường đã đủ cho bản đầu. Hướng dẫn cú pháp cơ bản có thể đối chiếu với Markdown Reference của CommonMark.

Viết khối lệnh để người đọc biết phải làm gì

Đặt lệnh trong code block, tách khỏi phần giải thích. Ghi rõ terminal cần mở ở đâu và điều kiện phải có trước. Nếu một lệnh tạo database hoặc ghi đè dữ liệu, cần mô tả đúng tác động thay vì gộp chung vào một chuỗi để người khác sao chép mù quáng.

Không đưa token, mật khẩu thật hoặc tệp môi trường của máy cá nhân vào README. Dùng tên biến và giá trị minh họa rõ ràng, chẳng hạn YOUR_API_KEY, đồng thời nói nơi người dùng lấy mã của họ. Một chuỗi trông như mã mẫu nhưng thực ra là khóa thật vẫn có thể bị người khác sử dụng.

Nếu dự án có nhiều cách chạy, chọn một đường chính dễ kiểm tra rồi dẫn tới tài liệu bổ sung. Đưa tất cả hướng dẫn cho Windows, Linux, container và hosting vào cùng một khối lệnh thường khiến người mới chọn nhầm bước.

Liên kết, ảnh và danh sách

Dùng văn bản liên kết có ý nghĩa, chẳng hạn “Hướng dẫn cấu hình”, thay vì nhiều dòng “bấm vào đây”. Với ảnh chụp, ghi alt mô tả nội dung ảnh để người không xem được hình vẫn hiểu điều bạn muốn chỉ ra.

Đường dẫn tương đối đến ảnh cần tính theo nơi README được hiển thị. Một ảnh có đường dẫn đúng trong repository chưa chắc đã xuất hiện trong trang HTML độc lập tải về, vì tệp ảnh không tự được nhúng vào HTML.

Với yêu cầu nhiều bước, danh sách đánh số sẽ dễ theo dõi hơn một đoạn văn dài. Với các lựa chọn độc lập, dùng gạch đầu dòng. Bảng có thể hữu ích cho so sánh, nhưng cách hỗ trợ bảng thuộc các biến thể Markdown khác nhau; hãy xem trước trên đúng nền tảng đích.

Xem trước và tải tệp bằng công cụ

  1. Mở Markdown Previewer.
  2. Dán nội dung vào ô Markdown và xem phần Preview.
  3. Kiểm tra tiêu đề, danh sách, khối lệnh và liên kết.
  4. Chọn Download .md để lưu nguồn, hoặc Download .html để lưu bản HTML dựng từ nội dung.
  5. Nếu dùng Copy HTML, kiểm tra lại nơi sẽ dán nội dung vì hệ thống đích có thể xử lý HTML khác.

Phần xem trước xử lý văn bản trên trình duyệt và làm sạch HTML trước khi chèn vào trang. Dù vậy, ảnh ngoài được nhúng trong tài liệu có thể khiến trình duyệt tải tài nguyên từ nguồn ảnh đó. Không nên hiểu “Markdown xử lý tại máy” là mọi tài nguyên bạn tự liên kết cũng không phát sinh kết nối mạng.

Kiểm tra README trước khi chia sẻ

Thử đọc như người chưa biết dự án và làm lại các bước trong một môi trường phù hợp. Lệnh có đúng tên tệp, đường dẫn và phiên bản không? Có bước cấu hình quan trọng đang được bạn làm bằng tay nhưng chưa ghi ra không?

Sau khi sửa, có thể dùng Diff Checker để đối chiếu bản cũ và bản mới. Nếu một phần hướng dẫn đã hết đúng, sửa hoặc ghi rõ giới hạn thay vì giữ lại như một lời hứa về chức năng.

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

Công cụ có kiểm tra các lệnh chạy đúng không? Không. Xem trước xác nhận cách hiển thị, không thực thi hoặc kiểm chứng hướng dẫn của dự án.

HTML tải xuống có giống hệt trên GitHub không? Không bảo đảm. Nền tảng, CSS và biến thể Markdown có thể khác nhau; hãy xem lại tại nơi xuất bản.

Có cần viết README bằng tiếng Anh không? Chọn ngôn ngữ phù hợp người dùng. Nếu có hai bản, ghi rõ cách chuyển ngôn ngữ và duy trì thông tin nhất quán thay vì dịch một lần rồi bỏ quên.