जो Markdown आपको वापस मिलता है, और उसे कैसे साफ़ करें

अंतिम समीक्षा

रूपांतरण आपको एक Markdown फ़ाइल देता है, तैयार दस्तावेज़ नहीं। यह एक छोटी व्यावहारिक मार्गदर्शिका है कि क्या निकलता है, किन हिस्सों पर भरोसा किया जा सकता है, और फ़ाइल के किसी रिपॉज़िटरी, विकी या नोट संग्रह में जाने से पहले कौन-से थोड़े-से संपादन करने लायक हैं।

7 मिनट का पाठ

आउटपुट असल में क्या है

कनवर्टर GitHub Flavored Markdown देता है — वही बोली जिसे GitHub, GitLab, Obsidian, Notion के आयात और अधिकांश स्टैटिक साइट जनरेटर उपयोग करते हैं। यह CommonMark है और साथ में कुछ जोड़ें, जिनमें यहाँ मायने रखने वाली चीज़ है pipe तालिकाएँ।

यह चुनाव जान-बूझकर है। सादे CommonMark में तालिका की कोई संरचना ही नहीं है, इसलिए उसे लक्ष्य बनाने वाला कनवर्टर या तो तालिकाएँ गिरा देता है या कच्चा HTML देता है। GFM की तालिकाएँ पाठ के रूप में भी पढ़ी जा सकती हैं और लगभग हर उस जगह समझी जाती हैं जहाँ Markdown समझा जाता है।

सफ़र में क्या बचता है

शीर्षकहाँ — सापेक्ष फ़ॉन्ट आकार से #, ##, ### के रूप में
अनुच्छेदहाँ — ऊर्ध्व अंतराल से
मोटा और तिरछाहाँ — फ़ॉन्ट के अपने भार और झुकाव से
बिंदु सूचियाँहाँ — शुरुआती बिंदु-चिह्नों से
क्रमांकित सूचियाँहाँ — शुरुआती अंकों से
तालिकाएँसरल आयताकार वाली, GFM pipe तालिकाओं के रूप में
इनलाइन codeहाँ — monospace खंडों से
लिंकहाँ, जहाँ PDF में असली लिंक एनोटेशन हो
चित्रनहीं — आउटपुट केवल पाठ और संरचना है
पाद-टिप्पणियाँपृष्ठ के अंत में सामान्य पाठ के रूप में, बिना लिंक
गणितउन्हीं अक्षरों के रूप में जिनसे बना है, LaTeX के रूप में नहीं
रंग और फ़ॉन्टनहीं — Markdown में इन्हें कहने का कोई तरीका नहीं

हर बार करने लायक पाँच संपादन

अधिकांश बदली हुई फ़ाइलों को उन्हीं थोड़े-से चक्करों की ज़रूरत होती है। इनमें दो मिनट लगते हैं और यही उस फ़ाइल में अंतर बनाते हैं जिसे खोजा जा सकता है और उसमें जिसे पढ़ा जा सकता है।

  • शीर्षकों की सीढ़ी ठीक कीजिए। आकार-आधारित सीमाएँ ऐसे स्तर देती हैं जो स्थानीय रूप से सही और समग्र रूप से असमान होते हैं — दस्तावेज़ में तीन H1 और एक भी H2 न होना संभव है। केवल शीर्षक सरसरी तौर पर देखिए और इस तरह पुनः क्रमित कीजिए कि नेस्टिंग दस्तावेज़ की असली रूपरेखा से मेल खाए।
  • टूटे अनुच्छेद फिर जोड़िए। उदार अंतराल वाला दस्तावेज़ अनुच्छेदों को पंक्ति के नरम अंत पर तोड़ देता है। ये छोटी पंक्तियों के ढेर जैसे पढ़े जाते हैं; इन्हें जोड़िए और बची हुई खाली पंक्तियाँ हटाइए।
  • शब्द-विभाजन ठीक कीजिए। दाएँ हाशिये पर हाइफ़न से संरेखित पाठ शब्दों को पंक्तियों के बीच तोड़ देता है। फ़ाइल में ऐसा हाइफ़न खोजिए जिसके तुरंत बाद पंक्ति-विराम हो।
  • हर तालिका जाँचिए। Markdown के स्तंभ मूल के सामने गिनिए और आख़िरी पंक्ति देखिए — अंतिम पंक्ति सबसे आम शिकार है। जो तालिका अपना आकार खो चुकी हो, उसे सुधारने से जल्दी अक्सर दोबारा टाइप करना होता है।
  • पृष्ठ का साज-सामान हटाइए। दोहराए जाने वाले हेडर और फ़ुटर पहचानकर हटा दिए जाते हैं, पर जो दस्तावेज़ उन्हें बदलता रहे — हर पृष्ठ पर अलग अध्याय शीर्षक — वह टुकड़े छोड़ सकता है।

तालिकाओं पर एक टिप्पणी

GFM की pipe तालिका में हर पंक्ति में कोष्ठों की संख्या समान चाहिए, और शीर्ष के नीचे की विभाजक पंक्ति पूरी तालिका के लिए स्तंभों की संख्या तय करती है। यदि कनवर्टर एक पंक्ति गिनने में चूक जाए, तो तालिका अमान्य हो जाती है और pipe चिह्नों समेत शाब्दिक पाठ के रूप में दिखती है।

यह दिखने वाली विफलता है, और यह राहत की बात है: आप इसे तुरंत देख लेंगे, बाद में पता चलने के बजाय। यह तालिका टूटी हुई है:

टूटी हुई: दूसरी पंक्ति में एक कोष्ठ कम है
| क्षेत्र | Q1 | Q2 |
| --- | --- | --- |
| उत्तर | 120 | 140 |
| दक्षिण | 95 |
| पूर्व | 88 | 102 |

इसे कैसे ठीक करें

छूटा हुआ कोष्ठ जोड़िए — यदि मूल कोष्ठ खाली था तो खाली ही। हर पंक्ति में उतने ही pipe होने चाहिए जितने विभाजक पंक्ति में हैं।

ठीक की हुई
| क्षेत्र | Q1 | Q2 |
| --- | --- | --- |
| उत्तर | 120 | 140 |
| दक्षिण | 95 |  |
| पूर्व | 88 | 102 |

एस्केपिंग, और आउटपुट में कभी-कभी बैकस्लैश क्यों आते हैं

Markdown उन अक्षरों को अर्थ देता है जो साधारण गद्य में भी आते हैं। तारांकन का अर्थ ज़ोर है, अंडरस्कोर का अर्थ ज़ोर है, पंक्ति के आरंभ में हैश का अर्थ शीर्षक है, और आरंभ में अंक और पूर्णविराम का अर्थ सूची-मद है।

जब ये अक्षर आपके दस्तावेज़ में स्वयं के रूप में आएँ — पाद-टिप्पणी का चिह्न, अंडरस्कोर वाला वेरिएबल नाम, वह पंक्ति जो सचमुच "1985." से शुरू होती है — तो उन्हें बैकस्लैश से एस्केप करना पड़ता है, वरना वे चुपचाप बदल देंगे कि दस्तावेज़ कैसे दिखता है। आउटपुट में बैकस्लैश आमतौर पर कनवर्टर की सावधानी है, गलती नहीं।

यदि कोई बैकस्लैश रास्ते में आ रहा हो, तो उसे हटाना सुरक्षित है, बशर्ते बाद में देख लें कि पंक्ति कैसी दिखती है।

फ़ाइल आगे कहाँ जाती है

Markdown सादा पाठ है, और शुरू में बदलने की वजह भी यही है: इसे grep से खोजा जा सकता है, diff से मिलाया जा सकता है, और पचास साल बाद भी वह हर चीज़ इसे पढ़ लेगी जो पाठ फ़ाइल खोल सकती है।

रिपॉज़िटरी के लिए इसे पेड़ में रखिए और कोड समीक्षा को अपना काम करने दीजिए। नोट संग्रह के लिए पहले शीर्षकों की सीढ़ी जाँचिए, क्योंकि अधिकांश संग्रह अपनी रूपरेखा उसी से बनाते हैं। स्टैटिक साइट के लिए वह front matter जोड़िए जो आपके जनरेटर को चाहिए — कोई कनवर्टर इसे गढ़ नहीं सकता, क्योंकि यह PDF में है ही नहीं। भाषा मॉडल को खिलाने के लिए, PDF को पुनर्प्राप्ति के लिए तैयार करने वाली गाइड देखिए; वह अलग काम है और उसकी प्राथमिकताएँ अलग हैं।