मास्टरिंग मार्कडाउन सूचियां: CommonMark और GitHub Flavored Markdown (GFM) इंडेंटेशन मानक
मार्कडाउन सूची रेंडरिंग की तकनीकी नींव
मार्कडाउन ने आधुनिक सॉफ़्टवेयर दस्तावेज़ीकरण, तकनीकी विनिर्देश दस्तावेज़ों, व्यक्तिगत ज्ञान आधारों और डेवलपर संचार के लिए मानक मार्कअप भाषा के रूप में खुद को स्थापित किया है। जबकि एकल-स्तरीय बुलेटेड सूचियां (- item) और क्रमांकित सूचियां (1. item) सरल दिखाई देती हैं, गहराई से नेस्टेड, बहु-स्तरीय दस्तावेज़ रूपरेखा का निर्माण महत्वपूर्ण स्वरूपण जटिलता पेश करता है। विभिन्न मार्कडाउन पार्सर—जैसे CommonMark, GitHub Flavored Markdown (GFM), Python-Markdown, और Pandoc—सूची मार्कर चयन, टैब-टू-स्पेस अनुपात और उप-ब्लॉक इंडेंटेशन से संबंधित सख्त, सूक्ष्म नियमों को लागू करते हैं।
जब सूचियों को विषम टेक्स्ट संपादकों (जैसे VS Code, Sublime Text, Xcode, Apple Notes, या Microsoft Word) में पेस्ट किया जाता है, तो मूक इंडेंटेशन त्रुटियां होती हैं। उप-आइटम पर एक भी गायब स्पेस मार्कडाउन कंपाइलर को प्राथमिक शीर्ष-स्तरीय आइटम या पृथक पैराग्राफ ब्लॉक के रूप में नेस्टेड चाइल्ड नोड की व्याख्या करने का कारण बनता है। Utiliome का नेस्टेड लिस्ट और इंडेंटेशन फॉर्मेटर आपके इनपुट टेक्स्ट स्ट्रक्चर AST (अब्स्ट्रैक्ट सिंटैक्स ट्री) को पार्स करके और मानकीकृत, विनिर्देश-अनुपालक मार्कडाउन को पुनर्जीवित करके इन पार्सिंग विसंगतियों को समाप्त करता है।
इंडेंटेशन नियम: 2-स्पेस बनाम 4-स्पेस दिशानिर्देश
तकनीकी दस्तावेज़ीकरण डिज़ाइन में सबसे लगातार विवादों में से एक यह है कि पदानुक्रमित स्तर पर 2 स्थानों या 4 स्थानों का उपयोग करके उप-सूचियों को इंडेंट किया जाए या नहीं। चुनाव लक्ष्य मार्कडाउन पार्सर विनिर्देश पर निर्भर करता है:
2-स्पेस इंडेंटेशन नियम (मानक GFM और Prettier): GitHub, Docusaurus, Nextra, और Obsidian जैसे आधुनिक वेब दस्तावेज़ीकरण पारिस्थितिक तंत्र में, प्रति इंडेंटेशन स्तर पर 2 स्थान मान्यता प्राप्त मानक है। 2-स्पेस सम्मेलन मूल आइटम के टेक्स्ट प्रारंभ के तहत चाइल्ड सामग्री को संरेखित करता है:
- Top-level item 1 - Nested child item 1.1 - Nested child item 1.2 - Deeply nested grandchild item 1.2.1 - Top-level item 24-स्पेस इंडेंटेशन नियम (सख्त CommonMark और Python-Markdown): सख्त CommonMark कार्यान्वयन के लिए उचित मूल ब्लॉक नियंत्रण की गारंटी देने के लिए ऑर्डर की गई सूचियों के अंदर चाइल्ड ब्लॉक, कोड स्निपेट्स और नेस्टेड सूचियों को 4 स्थानों (या 1 पूर्ण टैब स्टॉप) द्वारा इंडेंट करने की आवश्यकता होती है:
1. First ordered step in workflow - Associated sub-bullet A - Associated sub-bullet B 2. Second ordered step in workflowटैब बनाम स्पेस जाल: ASCII स्पेस वर्णों (
\x20) के साथ भौतिक टैब वर्णों (\t) को मिलाना टूटे हुए मार्कडाउन दस्तावेज़ीकरण रेंडरिंग का मुख्य कारण है। वेब रेंडरिंग इंजन टैब का असंगत रूप से अनुवाद करते हैं (अक्सर 4 या 8 डिस्प्ले कॉलम के रूप में), जिससे नेस्टेड आइटम दृष्टिगत रूप से संरेखण से बाहर हो जाते हैं। Utiliome आपकी स्पष्ट कॉन्फ़िगरेशन वरीयता के अनुसार स्वचालित रूप से सभी टैब वर्णों को समान स्पेस स्ट्रिंग्स में परिवर्तित करता है।
बुलेट मार्कर को सामान्य बनाना और ऑर्डर किए गए अनुक्रम को ठीक करना
मार्कडाउन अक्रमबद्ध सूचियों के लिए तीन अलग-अलग बुलेट वर्णों का समर्थन करता है: हाइफ़न (-), तारांकन चिह्न (*), और प्लस चिह्न (+)। जबकि तीनों वैध अक्रमबद्ध सूचियां HTML तत्व (<ul>) उत्पन्न करते हैं, एक ही दस्तावेज़ के भीतर मार्कर प्रकारों को मिलाने से दृश्य अव्यवस्था पैदा होती है और स्वचालित लिंटर जांच (जैसे markdownlint नियम MD004) विफल हो जाती है।
इसके अलावा, क्रमिक संपादन के दौरान क्रमांकित सूची संख्या अक्सर टूट जाती है। लेखक अक्सर क्रमांकित अनुक्रमों के मध्य में आइटम पेस्ट करते हैं या स्वतः-बढ़ते 1. सिंटैक्स पर भरोसा करते हैं:
<!-- Unformatted / Broken Input -->
* Feature A
- Feature B
+ Feature C
1. Initial step
1. Second step (copied from draft)
4. Out-of-order step
Utiliome का फॉर्मेटर आपकी टीम के कोड समीक्षा शैली दिशानिर्देशों के आधार पर सभी अक्रमबद्ध सूची मार्करों को आपके चयनित एकीकृत वर्ण (उदा. प्रत्येक आइटम को - में मानकीकृत करना) और पुन: संख्याओं के क्रमबद्ध अनुक्रमों (1., 2., 3.) को सामान्य करता है या उन्हें एकल-अंक वृद्धि (1., 1., 1.) में मानकीकृत करता है।