เก่ง Markdown Lists: มาตรฐานระยะย่อหน้า CommonMark & GitHub Flavored Markdown (GFM)
พื้นฐานทางเทคนิคของการแสดงผล Markdown List
Markdown ได้กลายเป็นภาษาจัดรูปแบบข้อความมาตรฐานสำหรับเอกสารซอฟต์แวร์สมัยใหม่ เอกสารข้อกำหนดทางเทคนิค ฐานความรู้ส่วนบุคคล และการสื่อสารของนักพัฒนา แม้ว่ารายการหัวข้อสัญลักษณ์ชั้นเดียว (- item) และรายการตัวเลข (1. item) จะดูเรียบง่าย แต่การสร้างโครงร่างเอกสารที่มีหลายระดับชั้นและซ้อนกันซับซ้อนนั้นนำมาซึ่งความยุ่งยากในการจัดรูปแบบ Parser ของ Markdown ที่แตกต่างกัน เช่น CommonMark, GitHub Flavored Markdown (GFM), Python-Markdown และ Pandoc ต่างบังคับใช้กฎที่เข้มงวดและมีรายละเอียดเกี่ยวกับเลือกสัญลักษณ์ สัดส่วนของ Tab ต่อ Space และระยะย่อหน้าของบล็อกย่อย
เมื่อคัดลอกรายการข้ามโปรแกรมแก้ไขข้อความที่หลากหลาย (เช่น VS Code, Sublime Text, Xcode, Apple Notes หรือ Microsoft Word) มักเกิดข้อผิดพลาดของการเว้นระยะย่อหน้าโดยไม่รู้ตัว การขาด Space ไปเพียงช่องเดียวในรายการย่อยจะทำให้ Markdown compiler ตีความโหนดลูกที่ซ้อนอยู่เป็นรายการระดับบนสุดหลักหรือเป็นบล็อกย่อหน้าที่แยกต่างหาก เครื่องมือ Nested List & Indentation Formatter ของ Utiliome ช่วยขจัดความผิดปกติในการแยกวิเคราะห์เหล่านี้โดยการวิเคราะห์โครงสร้างข้อความอินพุต AST (Abstract Syntax Tree) และสร้าง Markdown ที่ได้มาตรฐานตรงตามข้อกำหนดขึ้นมาใหม่
กฎระยะย่อหน้า: ข้อแนะนำ 2 ช่อง vs. 4 ช่อง
หนึ่งในข้อถกเถียงที่พบบ่อยที่สุดในการออกแบบเอกสารทางเทคนิคคือ ควรเว้นระยะย่อหน้ารายการย่อยด้วย 2 ช่อง หรือ 4 ช่องต่อระดับชั้น ตัวเลือกนี้ขึ้นอยู่กับข้อกำหนดของ Markdown parser ที่ใช้งาน:
กฎระยะย่อหน้า 2 ช่อง (มาตรฐาน GFM & Prettier): ในระบบนิเวศเอกสารเว็บสมัยใหม่ เช่น GitHub, Docusaurus, Nextra และ Obsidian การใช้ 2 ช่องต่อระดับย่อหน้าถือเป็นมาตรฐานที่ยอมรับกันอย่างแพร่หลาย ข้อกำหนด 2 ช่องจะจัดวางเนื้อหาลูกให้ตรงกับจุดเริ่มต้นของข้อความในรายการแม่:
- รายการระดับบนสุด 1 - รายการลูกที่ซ้อนอยู่ 1.1 - รายการลูกที่ซ้อนอยู่ 1.2 - รายการหลานที่ซ้อนอยู่ลึก 1.2.1 - รายการระดับบนสุด 2กฎระยะย่อหน้า 4 ช่อง (CommonMark แบบเคร่งครัด & Python-Markdown): การใช้งาน CommonMark แบบเคร่งครัดกำหนดให้บล็อกลูก โค้ดตัวอย่าง และรายการซ้อนภายในรายการตัวเลขต้องเว้นระยะย่อหน้า 4 ช่อง (หรือ 1 Tab) เพื่อรับประกันการครอบคลุมของบล็อกแม่ที่ถูกต้อง:
1. ขั้นตอนแบบลำดับแรกในกระบวนการทำงาน - หัวข้อย่อย A ที่เกี่ยวข้อง - หัวข้อย่อย B ที่เกี่ยวข้อง 2. ขั้นตอนแบบลำดับที่สองในกระบวนการทำงานกับดักระหว่าง Tab vs. Space: การผสมอักขระ Tab (
\t) เข้ากับอักขระ ASCII space (\x20) เป็นสาเหตุหลักที่ทำให้การแสดงผลเอกสาร Markdown เสียหาย เว็บเอ็นจินตีความอักขระ Tab ไม่สม่ำเสมอ (มักเป็น 4 หรือ 8 คอลัมน์แสดงผล) ทำให้รายการย่อยกระโดดไม่อยู่ในแนวเดียวกัน Utiliome จะแปลงอักขระ Tab ทั้งหมดเป็นสตริง Space ที่มีขนาดสม่ำเสมอตามการตั้งค่าของคุณโดยอัตโนมัติ
การปรับสัญลักษณ์หัวข้อให้เป็นมาตรฐานและการแก้ไขลำดับตัวเลข
Markdown รองรับสัญลักษณ์ 3 แบบสำหรับรายการที่ไม่มีลำดับ: ยติภังค์ (-), ดอกจัน (*) และเครื่องหมายบวก (+) แม้ว่าทั้งสามแบบจะสร้างองค์ประกอบ HTML รายการแบบไม่มีลำดับ (<ul>) ได้ถูกต้อง แต่การใช้สัญลักษณ์ปะปนกันในเอกสารเดียวกันจะทำให้เกิดความรกตาและไม่ผ่านการตรวจสอบ linter อัตโนมัติ (เช่น กฎ markdownlint MD004)
นอกจากนี้ การรันลำดับตัวเลขมักจะพังระหว่างการแก้ไข เพิ่มเติม หรือลบเนื้อหา ผู้เขียนมักจะวางรายการลงในตรงกลางของลำดับตัวเลข หรือพึ่งพาไวยากรณ์ 1. ที่เพิ่มขึ้นอัตโนมัติ:
<!-- ข้อความอินพุตที่ไม่จัดรูปแบบ / เสียหาย -->
* ฟีเจอร์ A
- ฟีเจอร์ B
+ ฟีเจอร์ C
1. ขั้นตอนแรก
1. ขั้นตอนที่สอง (คัดลอกมาจากร่าง)
4. ขั้นตอนที่ลำดับผิด
เครื่องมือจัดรูปแบบของ Utiliome จะปรับสัญลักษณ์รายการที่ไม่มีลำดับทั้งหมดให้เป็นอักขระเดียวที่คุณเลือก (เช่น ปรับทุกรายการเป็น -) และรันลำดับตัวเลขใหม่ตามลำดับ (1., 2., 3.) หรือปรับให้เป็นตัวเลขเดี่ยวที่เป็นมาตรฐาน (1., 1., 1.) ตามแนวทางการรีวิวโค้ดของทีมคุณ