Markdown को HTML में बदलें

फ़्रैगमेंट या पूरा पेज — और आपको कौन-सा चाहिए

काम के दो आउटपुट हैं और वे एक-दूसरे की जगह नहीं ले सकते। फ़्रैगमेंट सिर्फ़ कन्वर्ट किया गया मार्कअप है — हेडिंग, पैराग्राफ़, लिस्ट, लिंक — बिना किसी डॉक्यूमेंट रैपर के, और यही आपको तब चाहिए जब नतीजा किसी टेम्पलेट, CMS फ़ील्ड या दूसरे पेज में जाना हो। पूरा पेज इसमें doctype, head, कैरेक्टर-सेट की घोषणा और एक स्टाइलशीट जोड़ता है, ताकि वह अपने-आप खुले और ठीक-ठाक दिखे। पूरा पेज CMS में पेस्ट करने पर डॉक्यूमेंट के अंदर डॉक्यूमेंट बन जाता है; फ़्रैगमेंट को ब्राउज़र में खोलने पर बिना स्टाइल का टेक्स्ट मिलता है।

कन्वर्ज़न Markdown के उस विस्तारित सेट को कवर करता है जिस पर ज़्यादातर सहमति है: हेडिंग, ज़ोर (emphasis), लिस्ट, लिंक, इमेज, ब्लॉक कोट, टेबल, सिंटैक्स हाइलाइटिंग वाले फ़ेंस्ड कोड ब्लॉक, टास्क लिस्ट, स्ट्राइकथ्रू और फ़ुटनोट। हेडिंग को उनके टेक्स्ट से बने आइडेंटिफ़ायर मिलते हैं, ताकि उन पर सीधे लिंक किया जा सके — यही एंकर लिंक लंबे डॉक्यूमेंटेशन को इस्तेमाल लायक बनाते हैं।

Markdown के अंदर का रॉ HTML जैसा का तैसा आगे चला जाता है — यह स्पेसिफ़िकेशन का हिस्सा है और इस पर सोच-समझकर चलना चाहिए: इसका मतलब है कि किसी अनजान स्रोत की Markdown फ़ाइल में script टैग हो सकता है, और उसे कन्वर्ट करने पर बना पेज वह स्क्रिप्ट साथ लेकर चलेगा। अजनबियों का Markdown कभी भी बाद में HTML को सैनिटाइज़ किए बिना रेंडर न करें — कन्वर्ज़न कोई सुरक्षा दीवार नहीं है और कभी उसके लिए बना भी नहीं था।

दो चीज़ें जान-बूझकर रेंडर होने के बजाय कोड ब्लॉक के रूप में आती हैं। LaTeX नोटेशन में लिखे गणित के फ़ॉर्मूलों के लिए टाइपसेटिंग लाइब्रेरी चाहिए, और Mermaid डायग्राम के लिए डायग्राम रेंडरर — दोनों ही भारी डिपेंडेंसी हैं, और ग़लत रेंडर हुआ समीकरण दिखते हुए कोड से बुरा है। पूरा पेज कोई फ़ॉन्ट डाउनलोड करने के बजाय आम सिस्टम फ़ॉन्ट इस्तेमाल करता है, इसलिए वह ऑफ़लाइन काम करता है और Windows, macOS और Linux पर थोड़ा अलग दिखता है।

जब आपको कुछ और चाहिए

Pandoc वे हिस्से भी संभालता है जो यहां छोड़ दिए गए हैं, और उससे कहीं ज़्यादा: pandoc in.md -o out.html --mathjax --standalone --toc गणित को ठीक से रेंडर करता है, विषय-सूची बनाता है, और एक टेम्पलेट लेता है ताकि आउटपुट आपकी अपनी साइट जैसा दिखे। यह लगभग चालीस दूसरे फ़ॉर्मैट में और उनसे कन्वर्ट भी करता है, इसीलिए इसे एक बार इंस्टॉल कर लेना फ़ायदेमंद है।

किसी फ़ाइल के बजाय पूरी वेबसाइट के लिए, एक-एक पेज कन्वर्ट करने के बजाय कोई जनरेटर इस्तेमाल करें। Hugo, Eleventy, Jekyll और MkDocs Markdown से भरे फ़ोल्डर को नेविगेशन, सर्च और एक जैसी स्टाइलिंग वाली साइट में बदल देते हैं, और सोर्स बदलते ही उसे दोबारा बना देते हैं — जब भी एक से ज़्यादा डॉक्यूमेंट हों, असली काम यही होता है।