Softonic

เครื่องสร้างไฟล์ README

ขั้นตอน 1 / 4 README.md
ถัดไป

รีโปที่ว่างเปล่าสร้างความประทับใจแรกที่ไม่ดี กรอกชื่อโปรเจกต์ สโลแกนหนึ่งบรรทัด รายการฟีเจอร์ คำสั่งติดตั้ง โค้ดเริ่มต้นอย่างรวดเร็ว ผู้เขียน และใบอนุญาต แล้วเครื่องมือนี้จะสร้างไฟล์ README แบบ Markdown ที่สะอาดตา พร้อมลำดับชั้นของหัวข้อที่ถูกต้องและบล็อกโค้ดแบบมีรั้ว นั่นคือส่วนต่าง ๆ ที่ GitHub แสดงบนหน้าโปรเจกต์ของคุณ คัดลอก บันทึกเป็น README.md ที่รากของรีโป แล้วพุช หัวข้อของแต่ละส่วนเขียนเป็นภาษาอังกฤษ ซึ่งเป็นธรรมเนียมที่แทบจะเป็นสากลของ README โอเพนซอร์ส ส่วนข้อความของคุณเองจะปรากฏตรงตามที่คุณพิมพ์ ไม่ว่าจะเป็นภาษาใด

วิธีเขียนไฟล์ README

  1. 1

    เพิ่มข้อมูลพื้นฐาน

    ชื่อโปรเจกต์ URL ของรีโป (ไม่บังคับ) และสโลแกนหนึ่งบรรทัด ชื่อจะกลายเป็นหัวข้อ `#` ส่วนสโลแกนจะกลายเป็นบล็อกคำพูดอ้างอิงด้านล่าง

  2. 2

    ระบุฟีเจอร์และการเริ่มต้นอย่างรวดเร็ว

    หนึ่งฟีเจอร์ต่อหนึ่งบรรทัด (แต่ละบรรทัดกลายเป็นจุดหัวข้อ) พร้อมโค้ดเริ่มต้นอย่างรวดเร็วสั้น ๆ ที่จะถูกห่อไว้ในบล็อกโค้ดแบบมีรั้ว

  3. 3

    การติดตั้ง ใบอนุญาต และผู้เขียน

    คำสั่งติดตั้งจะอยู่ในบล็อกโค้ด `bash` ใต้หัวข้อ Installation เพิ่มใบอนุญาต (MIT, Apache-2.0…) และบรรทัดผู้เขียนที่เป็นตัวเลือก

  4. 4

    คัดลอก Markdown

    คลิกคัดลอก แล้ววางผลลัพธ์เป็น `README.md` ที่รากของรีโป จากนั้นพุช เวอร์ชันที่เรนเดอร์แล้วจะปรากฏบนหน้าโปรเจกต์

README ที่ดีควรมีอะไรบ้าง

คู่มือสไตล์ของ GitHub เองและข้อกำหนด standard-readme ที่ใช้กันอย่างแพร่หลายเห็นตรงกันเรื่องลำดับ วางส่วนที่กวาดสายตาอ่านได้ไว้ด้านบน เพราะผู้ที่เข้ามาที่รีโปของคุณจะตัดสินใจภายใน 20 วินาทีว่าจะอ่านต่อหรือไม่

หัวข้อ ตำแหน่ง วัตถุประสงค์
ชื่อเรื่อง + สโลแกน บรรทัดที่ 1–2 # Project ตามด้วยหนึ่งประโยคว่ามันทำอะไร
แบดจ์ บรรทัดที่ 3–5 สถานะ CI, เวอร์ชัน npm, ใบอนุญาต, ความครอบคลุม
การติดตั้ง ส่วนบนของหน้า คำสั่งเดียวที่ใครก็คัดลอกได้
การใช้งาน ส่วนบนของหน้า โค้ดสั้นที่สุดที่ให้ผลลัพธ์
API / ตัวเลือก กลาง ตารางของแฟล็ก คีย์การตั้งค่า หรือเอ็นด์พอยต์
การมีส่วนร่วม ใกล้ท้าย ลิงก์ไปยัง CONTRIBUTING.md จรรยาบรรณ และแนวปฏิบัติของ PR
ใบอนุญาต ท้ายสุด ตัวระบุ SPDX พร้อมลิงก์ไปยัง LICENSE

แบดจ์ที่ช่วยได้จริง

URL ของ Shields.io เป็นไปตามรูปแบบที่คาดเดาได้: https://img.shields.io/badge/<label>-<message>-<color>.svg แบดจ์สดที่มีประโยชน์จะชี้ไปที่สถานะการบิลด์ เวอร์ชันของแพ็กเกจ และจำนวนการดาวน์โหลด ไม่ใช่ตัวชี้วัดเพื่อความโก้หรู โดยทั่วไปแบดจ์สี่อันก็เพียงพอ ส่วนที่มากกว่านั้นเป็นเพียงสิ่งรบกวน

ข้อผิดพลาดที่พบบ่อยใน README

  • ไม่มีคำสั่งติดตั้งในบรรทัดแรกของส่วนการติดตั้ง ผู้อ่านจะกวาดสายตาหา npm install หรือ pip install ถ้าคุณซ่อนมันไว้หลังข้อความ พวกเขาก็จะจากไป
  • ภาพหน้าจอขนาด 3 MB ปรับขนาดให้กว้าง 800 พิกเซลแล้วบีบอัด GitHub จะแสดงมันให้อยู่แล้ว แต่ผู้อ่านบนมือถือต้องจ่ายค่าแบนด์วิดท์
  • แบดจ์ที่ล้าสมัย แบดจ์ CI สีแดงบอกผู้เข้าชมว่าโปรเจกต์เสีย ให้แก้ CI หรือลบแบดจ์ทิ้ง
  • ไม่มีใบอนุญาต หากไม่มีใบอนุญาต โค้ดของคุณจะเป็น “สงวนลิขสิทธิ์ทั้งหมด” โดยค่าเริ่มต้น และบริษัทต่าง ๆ ใช้งานไม่ได้

คำถามที่พบบ่อย

ใช่ บล็อกโค้ดแบบมีรั้ว รายการหัวข้อย่อย และหัวข้อสไตล์ ATX (คำนำหน้า #) ทั้งหมดแสดงผลบน GitHub, GitLab และ Bitbucket โดยไม่ต้องแก้ไข คำสั่งติดตั้งจะถูกกำกับเป็นบล็อก bash ส่วนบล็อกเริ่มต้นอย่างรวดเร็วจะไม่มีการกำกับ เพื่อให้คุณกำหนดภาษาเอง

สำหรับระบบนิเวศส่วนใหญ่ ใช้ README.md ใช้ .rst เฉพาะเมื่อคุณเผยแพร่แพ็กเกจ Python ที่เอกสารอยู่บน Read the Docs และต้องการให้ Sphinx นำไฟล์นี้มาใช้เป็นหน้าแรก

เมื่อคุณระบุ URL ของรีโป เครื่องมือจะเพิ่มแบดจ์ใบอนุญาตแบบคงที่หนึ่งอัน (https://img.shields.io/badge/license-<type>-blue.svg) หากต้องการแบดจ์สด (สถานะการบิลด์ เวอร์ชัน การดาวน์โหลด) ให้คัดลอกรูปแบบ URL ของ shields.io แล้ววางลงในผลลัพธ์ด้วยตัวเอง

ไม่ ไฟล์ README ประกอบขึ้นจากค่าในฟอร์ม และไม่มีการบันทึกสิ่งใด ปิดแท็บแล้วข้อมูลก็หายไป

เครื่องมือที่เกี่ยวข้อง

ตารางอ้างอิง ASCII

ตาราง ASCII ครบตั้งแต่ 0 ถึง 127 พร้อมค่าเลขฐานสิบ ฐานสิบหก ฐานแปด ฐานสอง และรูปแบบการอ้างอิงอักขระแบบตัวเลขของ HTML รวม NUL, LF และ DEL

อ้างอิงตัวอักษร HTML

รายการที่สามารถค้นหาได้ขององค์ประกอบ HTML พร้อมรหัสชื่อและรหัสตัวเลข รวมถึงฟังก์ชันสำเนาด้วยคลิกเดียวสำหรับตัวอักษรพิเศษและสัญลักษณ์ต่างๆ

ตารางอ้างอิงแป้นพิมพ์ลัด

ค้นหาแป้นพิมพ์ลัดเริ่มต้นตามเอกสารของ VS Code, Chrome และ Bash ที่ใช้ GNU Readline บน macOS, Windows และ Linux

ตัวตรวจสอบอีเมล

ตรวจสอบที่อยู่อีเมล: ตรวจไวยากรณ์ RFC 5322 ค้นหา MX เรกคอร์ดแบบเรียลไทม์ พร้อมรายละเอียดส่วนท้องถิ่น โดเมน และความยาว ไม่มีการส่งอีเมลใด ๆ

เครื่องมือสร้าง EditorConfig

สร้างไฟล์ .editorconfig จากกฎการเยื้อง การจบบรรทัด และชุดอักขระของคุณ แล้วเพิ่มเซกชันที่ถูกต้องให้ทุกภาษาในรีโพซิทอรี ทั้ง Python, Go, YAML, Makefile และอื่น ๆ

แปลงจาก CSV เป็น JSON

แปลงไฟล์ CSV ที่มีแถวหัวข้อให้เป็น JSON ในรูปแบบอาร์เรย์ของออบเจกต์ โดยแถวหัวข้อจะทำหน้าที่เป็นคีย์ และแถวข้อมูลจะกลายเป็นออบเจกต์ เพื่อใช้งานกับ API และโค้ด JavaScript

เครื่องมือนี้มีให้บริการในภาษาอื่น