Softonic

Bộ tạo README

Bước 1 / 4 README.md
Tiếp theo

Kho lưu trữ trống tạo ấn tượng đầu tiên không tốt. Điền tên dự án, một khẩu hiệu một dòng, danh sách tính năng, lệnh cài đặt, một đoạn khởi động nhanh, tác giả và giấy phép, rồi bộ tạo này sẽ xuất ra một README Markdown gọn gàng với cấu trúc tiêu đề đúng và khối mã có rào: chính là các mục mà GitHub hiển thị trên trang dự án của bạn. Sao chép, lưu thành README.md ở gốc kho lưu trữ, rồi đẩy (push). Tiêu đề các mục được viết bằng tiếng Anh, quy ước gần như phổ quát của README mã nguồn mở; còn văn bản của riêng bạn hiển thị đúng như bạn gõ, bằng bất kỳ ngôn ngữ nào.

Cách soạn README

  1. 1

    Thêm thông tin cơ bản

    Tên dự án, URL kho lưu trữ (tùy chọn) và một khẩu hiệu một dòng. Tên trở thành tiêu đề `#`; khẩu hiệu trở thành khối trích dẫn bên dưới.

  2. 2

    Liệt kê tính năng và khởi động nhanh

    Mỗi dòng một tính năng (mỗi dòng thành một gạch đầu dòng), cùng một đoạn khởi động nhanh ngắn được bọc trong khối mã có rào.

  3. 3

    Cài đặt, giấy phép và tác giả

    Lệnh cài đặt nằm trong khối mã `bash` dưới mục Installation; thêm giấy phép (MIT, Apache-2.0…) và một dòng tác giả tùy chọn.

  4. 4

    Sao chép Markdown

    Nhấp sao chép và dán kết quả thành `README.md` ở gốc kho lưu trữ. Đẩy lên, phiên bản đã kết xuất sẽ xuất hiện trên trang dự án.

Một README tốt nên có những gì

Hướng dẫn phong cách riêng của GitHub và đặc tả standard-readme được dùng rộng rãi đều thống nhất về thứ tự. Đặt những phần dễ lướt đọc lên trên: người ghé vào kho lưu trữ của bạn quyết định trong 20 giây có đọc tiếp hay không.

Phần Vị trí Mục đích
Tiêu đề + khẩu hiệu Dòng 1–2 # Project theo sau là một câu về việc nó làm gì
Huy hiệu Dòng 3–5 Trạng thái CI, phiên bản npm, giấy phép, độ bao phủ
Cài đặt Phía trên nếp gấp Một lệnh duy nhất mà ai cũng có thể sao chép
Sử dụng Phía trên nếp gấp Đoạn mã tối thiểu tạo ra kết quả
API / tùy chọn Ở giữa Bảng cờ, khóa cấu hình hoặc điểm cuối
Đóng góp Gần cuối Liên kết đến CONTRIBUTING.md, quy tắc ứng xử, quy ước PR
Giấy phép Cuối cùng Mã định danh SPDX cùng liên kết đến LICENSE

Huy hiệu thực sự hữu ích

URL của Shields.io tuân theo một mẫu dễ đoán: https://img.shields.io/badge/<label>-<message>-<color>.svg. Huy hiệu trực tiếp hữu ích trỏ tới trạng thái build, phiên bản gói và số lượt tải, chứ không phải các chỉ số phô trương. Thường bốn huy hiệu là đủ; nhiều hơn chỉ là nhiễu.

Lỗi thường gặp trong README

  • Không có lệnh cài đặt ở dòng đầu của mục Cài đặt. Người đọc lướt tìm npm install hoặc pip install; nếu bạn giấu nó sau văn bản, họ sẽ rời đi.
  • Ảnh chụp màn hình 3 MB. Thu nhỏ về chiều rộng 800 px rồi nén; GitHub vẫn phục vụ chúng, nhưng người đọc trên di động phải trả chi phí băng thông.
  • Huy hiệu lỗi thời. Huy hiệu CI màu đỏ cho khách biết dự án đang hỏng. Hãy sửa CI hoặc gỡ huy hiệu đi.
  • Thiếu giấy phép. Không có giấy phép, mã của bạn mặc định là “giữ mọi quyền” và các công ty không thể sử dụng.

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

Có. Khối mã có rào, danh sách gạch đầu dòng và tiêu đề kiểu ATX (tiền tố #) đều hiển thị trên GitHub, GitLab và Bitbucket mà không cần chỉnh sửa. Lệnh cài đặt được gắn thẻ là khối bash; khối khởi động nhanh để không gắn thẻ để bạn tự chỉ định ngôn ngữ.

Với hầu hết hệ sinh thái, dùng README.md. Chỉ dùng .rst nếu bạn xuất bản một gói Python có tài liệu đặt trên Read the Docs và muốn Sphinx tái sử dụng tệp này làm trang đích.

Khi bạn cung cấp URL kho lưu trữ, bộ tạo thêm một huy hiệu giấy phép tĩnh duy nhất (https://img.shields.io/badge/license-<type>-blue.svg). Nếu cần huy hiệu trực tiếp (trạng thái build, phiên bản, lượt tải), hãy sao chép một mẫu URL shields.io và tự dán vào kết quả.

Không. README được lắp ghép từ các giá trị biểu mẫu và không có gì được lưu. Đóng tab lại là dữ liệu biến mất.

Công cụ liên quan

Bảng tham chiếu ASCII

Bảng ASCII đầy đủ từ 0 đến 127 với giá trị thập phân, thập lục phân, bát phân, nhị phân và ký hiệu tham chiếu ký tự số HTML, gồm NUL, LF và DEL.

Tham chiếu ký tự HTML

Danh sách có thể tìm kiếm các thực thể HTML, mã tên và mã số tương ứng của chúng, cùng chức năng sao chép chỉ với một cú nhấp cho các ký tự đặc biệt và biểu tượng.

Bảng tham khảo phím tắt

Tìm phím tắt mặc định theo tài liệu của VS Code, Chrome và Bash dùng GNU Readline trên macOS, Windows và Linux.

Trình giải mã mã JavaScript (JavaScript Deobfuscator)

Giải mã mã JavaScript đã được rút gọn hoặc nén bằng cách đổi tên biến, giải mã chuỗi và mảng, đảo ngược cấu trúc dòng điều khiển và làm đẹp mã.

Chuyển đổi Lưu trữ Dữ liệu

Chuyển đổi kích thước dữ liệu giữa bit, byte, kilobyte, megabyte, gigabyte, terabyte và petabyte, theo quy ước thập phân (1000) hoặc nhị phân (1024).

Trình định dạng HTML

Định dạng HTML cục bộ trong trình duyệt với thụt lề hai hoặc bốn khoảng trắng. HTML không được tải lên hoặc xác thực.

Công cụ này có phiên bản bằng các ngôn ngữ khác