เครื่องมือแปลง README เป็น PDF

ไฟล์ README.md คือเอกสาร Markdown ที่อธิบายโครงการ คลังเก็บข้อมูล แพ็กเกจ แอปพลิเคชัน ชุดข้อมูล หรือเวิร์กโฟลว์

ไฟล์ README มักจะรวมถึง:

• ชื่อโครงการและข้อมูลสรุป
• คำแนะนำการติดตั้ง
• ตัวอย่างการใช้งาน
• ข้อมูลโค้ดบรรทัดคำสั่ง (CLI)
• ตัวอย่างการตั้งค่าคอนฟิก
• รายการคุณสมบัติ
• รายการงาน
• ตาราง
• ภาพหน้าจอ
• ป้ายสัญลักษณ์ (badge)
• คำแนะนำการมีส่วนร่วม
• ข้อมูลใบอนุญาตหรือการสนับสนุน
• ลิงก์ไปยังเอกสารและการเผยแพร่

นามสกุล .md หมายความว่าไฟล์ถูกเขียนด้วย Markdown การแปลงเป็น PDF จะสร้างเอกสารที่มีรูปแบบคงที่ในขณะที่ยังคงแหล่งข้อมูล Markdown เป็นรุ่นที่แก้ไขได้

PDF มีประโยชน์เมื่อ README จำเป็นต้องออกจากคลังเก็บข้อมูลเดิม หรือต้องถูกตรวจสอบในฐานะเอกสารที่มีการแบ่งหน้า

เหตุผลทั่วไป ได้แก่:

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

README ต้นฉบับควรยังคงเป็นแหล่งข้อมูลที่ต้องบำรุงรักษา ให้สร้าง PDF ใหม่หลังจากที่มีการเปลี่ยนแปลงใน README

SolConverter รองรับองค์ประกอบ Markdown ที่ใช้บ่อยในไฟล์ README

สิ่งเหล่านี้รวมถึง:

• หัวข้อ ATX และ Setext
• ข้อความตัวหนา ตัวเอียง และตัวขีดฆ่า
• รายการแบบเรียงลำดับและไม่เรียงลำดับ
• รายการซ้อนกัน
• รายการงาน GFM
• บล็อกคำพูด
• ลิงก์ Markdown และลิงก์อัตโนมัติ
• โค้ดอินไลน์
• บล็อกโค้ดแบบมีรั้วคั่นโดยใช้เครื่องหมาย backticks หรือ tildes
• ป้ายกำกับภาษาของบล็อกโค้ด
• ตาราง GFM พร้อมการจัดตำแหน่ง
• ตาราง HTML ดิบที่ปลอดภัย
• ส่วน details และ summary
• kbd, sub, sup, figure และ figcaption
• สมอหัวข้อ
• YAML front matter ที่จุดเริ่มต้นของซอร์ส

รั้วโค้ดที่มีเครื่องหมายดอลลาร์หรือตัวคั่นที่คล้ายกับ LaTeX จะยังคงเป็นโค้ดต่อไปแทนที่จะถูกตีความว่าเป็นสมการ

ไฟล์ README มักจะประกอบด้วยคำสั่งในการติดตั้ง, ไฟล์คอนฟิก, ตัวอย่าง API, ตัวแปรสภาพแวดล้อม และโค้ดตัวอย่าง

SolConverter ใช้การไฮไลต์ไวยากรณ์ด้วย Highlight.js เมื่อรู้จักภาษาของบล็อกโค้ด ส่วนภาษาที่ไม่รู้จักจะยังคงรักษารูปแบบต้นฉบับไว้อย่างปลอดภัย

บล็อกโค้ดใช้ฟอนต์ Monospace โดยเฉพาะและสไตล์การพิมพ์ที่ช่วยแยกโค้ดออกจากคำอธิบายโดยรอบ โค้ดจะยังคงแสดงผลจากซ้ายไปขวาแม้ใน README ที่เขียนจากขวาไปซ้าย

README ทางเทคนิคอาจมีสูตรคณิตศาสตร์, เมทริกซ์, สัญลักษณ์ทางวิทยาศาสตร์, นิพจน์ความน่าจะเป็น หรือเคมี

SolConverter รองรับเอาต์พุต MathJax SVG สำหรับตัวคั่นคณิตศาสตร์ทั่วไปของ Markdown, สภาพแวดล้อมสมการ AMS, Presentation MathML, Content MathML ขั้นพื้นฐาน และนิพจน์เคมีที่เขียนด้วย \ce{...}

คณิตศาสตร์ที่รองรับ ได้แก่:

• นิพจน์อินไลน์ $...$ และ \(...\)
• นิพจน์จอแสดงผล $$...$$ และ \[...\]
• สภาพแวดล้อมสมการและการจัดแนว
• เศษส่วน, ราก, ผลรวม, อินทิกรัล, ลิมิต และเมทริกซ์
• มาโครระดับเอกสาร
• นิพจน์การบวกที่ยาวซึ่งต้องขึ้นบรรทัดใหม่

คณิตศาสตร์จะถูกแสดงผลเป็น SVG เพื่อให้คงความคมชัดใน PDF คณิตที่ใช้งานไม่ได้สามารถแสดงผลด้วยภาพสำรองในตัวเครื่องได้โดยไม่ต้องหยุดการแปลงส่วนที่เหลือของ README

ไฟล์ README มักใช้ไดอะแกรมเพื่ออธิบายสถาปัตยกรรม, ลำดับขั้นตอน, สถานะ, เวิร์กโฟลว์ หรือความสัมพันธ์ของส่วนประกอบ

บล็อกโค้ด Mermaid ที่ถูกต้องจะแสดงผลเป็น SVG ภายในเครื่อง นอกจากนี้ยังรองรับ ZenUML ผ่านการรวมระบบ Mermaid ไดอะแกรมจะถูกจำกัดตามความกว้างของหน้ากระดาษและประมวลผลอย่างอิสระ

หากไดอะแกรมใดไม่ถูกต้อง ตัวแปลงจะแทรกรูปภาพสำรองพร้อมซอร์สโค้ด และประมวลผลส่วนที่เหลือต่อไป

PlantUML, Graphviz, D2, WaveDrom, BPMN, Nomnoml และ TikZ แบบเต็มระบบยังไม่รองรับในขณะนี้ และไม่ควรโฆษณาในหน้านี้

ตัวแปลงรองรับรูปภาพสาธารณะ HTTP และ HTTPS รวมถึงรูปภาพข้อมูล base64 ที่ถูกต้องในรูปแบบ PNG, GIF, JPEG, WebP และ SVG

รูปภาพจะถูกปรับขนาดให้พอดีกับหน้ากระดาษและคงอัตราส่วนภาพไว้ โดยจะสามารถรักษารูปภาพประกอบ, คำบรรยายภาพ, ข้อความ alt, ชื่อเรื่อง, ขนาดความกว้างที่ปลอดภัย และการจัดแนวได้

อย่างไรก็ตาม README ในที่เก็บข้อมูลจำนวนมากจะใช้เส้นทางสัมพัทธ์ เช่น:

./images/screenshot.png
docs/architecture.svg
../assets/demo.gif

กระบวนการอัปโหลดปัจจุบันไม่ได้นำโฟลเดอร์ของคลังเก็บข้อมูลมาด้วย และไม่สามารถแก้ปัญหาทรัพยากรสัมพัทธ์เหล่านั้นได้โดยอัตโนมัติ ให้เปลี่ยนเป็น URL รูปภาพสาธารณะ หรือรูปภาพข้อมูล base64 ก่อนที่จะเริ่มสร้าง PDF

ป้ายสัญลักษณ์ (badge) มักใช้ URL รูปภาพสาธารณะและอาจแสดงผลได้เมื่อโฮสต์รูปภาพเข้าถึงได้แบบสาธารณะ หากป้ายหรือรูปภาพไม่สามารถโหลดได้ SolConverter จะแทรกพื้นที่สำรองข้อมูลในเครื่องและทำการแปลงต่อ

ลิงก์ Markdown ใน README อาจเป็นลิงก์แบบสัมบูรณ์ ลิงก์สัมพัทธ์ของที่เก็บข้อมูล หรือลิงก์ส่วนย่อยของหน้า

ลิงก์ HTTP และ HTTPS แบบสัมบูรณ์ยังคงใช้งานได้ภายนอกคลังเก็บข้อมูล ลิงก์สัมพัทธ์ เช่น ./docs/setup.md หรือ ../CONTRIBUTING.md อาจไม่ชี้ไปยังปลายทางที่ถูกต้องหลังจากที่ README กลายเป็น PDF แบบสแตนด์โฮล

ก่อนที่จะแชร์ PDF:

• แทนที่ลิงก์สัมพัทธ์ที่สำคัญด้วย URL สัมบูรณ์ที่เป็นสาธารณะ
• เขียนคำแนะนำที่สำคัญออกมาตรง ๆ แทนที่จะพึ่งพาเฉพาะไฟล์ที่เชื่อมโยง
• ตรวจสอบลิงก์ของหัวข้อหลังจากการแสดงผล
• ตรวจสอบว่าเอกสารยังอ่านเข้าใจอยู่หรือไม่โดยไม่ต้องมีระบบนำทางของที่เก็บข้อมูล
• ใส่ข้อมูลเวอร์ชันหรือข้อมูลการเผยแพร่เมื่อต้องการบันทึก PDF ไว้เป็นเอกสารเก่า

GitHub README ยังคงเป็นไฟล์ Markdown แต่ GitHub อาจเพิ่มบริบทของคลังเก็บข้อมูลที่ไม่ได้มีอยู่ในตัวไฟล์ที่อัปโหลดเอง

ไฟล์ PDF สามารถคงโครงสร้าง GFM ที่รองรับ เช่น ตาราง รายการงาน รั้วโค้ด ลิงก์อัตโนมัติ และหัวข้อต่าง ๆ นอกจากนี้ยังแสดงผลนิพจน์ MathJax และไดอะแกรม Mermaid ที่รองรับได้

เครื่องมือแปลงนี้ไม่ได้จำลององค์ประกอบส่วนต่อประสานผู้ใช้ทั้งหมดของ GitHub ส่วนที่เป็นแท็บคลังเก็บข้อมูล, จำนวนปัญหา (issue), วิดเจ็ตการเผยแพร่, ตัวเลือกสาขา, การ์ดที่สร้างแบบไดนามิก และส่วนตกแต่งอื่น ๆ ของ GitHub ไม่ได้เป็นส่วนหนึ่งของซอร์สโค้ด Markdown

สำหรับ PDF แบบสแตนด์โฮลที่สะอาดที่สุด ตรวจสอบให้แน่ใจว่า README ได้ระบุข้อมูลตัวตนของโครงการ บริบทของรุ่น และลิงก์สำคัญไว้ในตัวเอกสารเองแล้ว

เอกสาร PDF ของ README สามารถทำหน้าที่ส่งมอบข้อมูลทางเทคนิคสั้น ๆ เมื่อผู้อ่านต้องการ:

• ภาพรวมโครงการ
• ขั้นตอนการติดตั้งและตั้งค่า
• ตัวอย่างคำสั่ง
• ข้อกำหนดการตั้งค่าคอนฟิก
• ไดอะแกรมสถาปัตยกรรม
• ตัวอย่าง API
• บันทึกย่อการทำงาน
• คำแนะนำการแก้ไขปัญหา
• รายละเอียดการมีส่วนร่วมหรือการสนับสนุน

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

คลังเก็บข้อมูลมีการเปลี่ยนแปลงอยู่ตลอดเวลา การแปลง README เป็น PDF จะช่วยสร้างภาพบันทึกข้อมูลที่อ่านง่ายซึ่งสัมพันธ์กับรุ่น การส่งมอบ การตรวจสอบ หรือเป้าหมายสำคัญ

ก่อนจะจัดเก็บประวัติ:

1. add the project or package version;
2. รวมวันที่ที่เกี่ยวข้องหรือตัวระบุรุ่นเผยแพร่
3. ตรวจสอบความถูกต้องของคำสั่งและตัวอย่างคอนฟิก
4. แทนที่ลิงก์ชั่วคราว
5. ตรวจสอบรูปภาพ ไดอะแกรม และสมการ
6. สร้างและตรวจสอบไฟล์ PDF ขั้นสุดท้าย
7. จัดเก็บ PDF ไว้คู่กับบันทึกการเผยแพร่

PDF ที่สร้างขึ้นเป็นเพียงภาพบันทึกสถานะ ไม่ใช่สิ่งที่จะมาแทนที่ไฟล์ README ดั้งเดิมในระบบควบคุมเวอร์ชัน

ไฟล์ README อาจมี HTML ดิบ, URL รูปภาพระยะไกล และบล็อกที่มีรูปแบบผิดเพี้ยน

SolConverter ทำความสะอาด HTML ที่แสดงผล ลบสคริปต์และตัวจัดการเหตุการณ์ ปฏิเสธ URL ที่ไม่ปลอดภัย จำกัด HTML ดิบให้อยู่ในรายการที่อนุญาต จำกัดความกว้างของตาราง ใช้นโยบายความปลอดภัยเนื้อหาที่จำกัด และบล็อกคำขอเบราว์เซอร์ภายนอกนโยบายรูปภาพที่อนุญาต

ไฟล์ในเครื่อง ปลายทาง localhost ที่อยู่ IP ส่วนตัว URL javascript: และโปรโตคอลทรัพยากรที่ไม่รองรับจะถูกบล็อก รูปภาพ สมการ และไดอะแกรมที่ไม่ถูกต้องจะถูกจัดการแบบเฉพาะจุดหากเป็นไปได้เพื่อให้ส่วนที่เหลือของ README สามารถแสดงผลต่อไปได้

SolConverter ใช้เลย์เอาต์เอกสารที่สม่ำเสมอกับไฟล์ README

เว็บฟอร์มปัจจุบันใช้:

• ขนาดหน้า A4
• แนวตั้ง
• ระยะขอบที่จัดการเพื่อการอ่านที่ง่ายขึ้น
• หมายเลขหน้าในรูปแบบ หน้าปัจจุบัน / หน้าทั้งหมด
• ชื่อเอกสารเอาต์พุตตามชื่อไฟล์ README
• พิมพ์ภาพพื้นหลัง

เลย์เอาต์แนวตั้งออกแบบมาเพื่อการอ่านทั่วไป ให้ตรวจสอบตัวอย่างของตารางขนาดกว้างและโค้ดก่อนทำการดาวน์โหลดเสมอ

ใช้หน้าเฉพาะสำหรับ README นี้เมื่อต้นทางเป็นไฟล์ README โครงการ และคุณต้องการคำแนะนำเกี่ยวกับโค้ดบล็อก, โครงสร้าง GFM, ป้ายสัญลักษณ์, รูปภาพสัมพัทธ์ของคลังเก็บข้อมูล และลิงก์ของคลังเก็บข้อมูล

ใช้เครื่องมือ แปลง Markdown เป็น PDF หลักสำหรับรายงาน เอกสารทางคณิตศาสตร์ บันทึกย่อทางเทคนิค ข้อเสนอโครงการ เอกสารหลายภาษา และไฟล์ .md ทั่วไป

ทั้งสองหน้าใช้ความสามารถในการแปลงหลักเหมือนกัน แต่ให้บริการสำหรับผู้ใช้ที่แตกต่างกันและให้คำแนะนำในการเตรียมการที่ต่างกัน

• แปลงไฟล์ Markdown ใด ๆ เป็น PDF
• แปลง PDF เป็น Markdown
• แปลง HTML เป็น Markdown
• แปลง Word เป็น Markdown
• เรียกดูเครื่องมือทั้งหมดในการแปลงเป็น Markdown