मार्कडाउन स्रोत को प्रस्तुति से अलग करता है
मार्कडाउन फ़ाइल सामान्य टेक्स्ट होती है, जो आमतौर पर .md एक्सटेंशन के साथ सहेजी जाती है। स्रोत बिना किसी विशेष एप्लिकेशन के समझ में आता रहता है, जबकि GitHub, डॉक्यूमेंटेशन टूल, स्टैटिक-साइट जनरेटर और एडिटर इसे टाइपोग्राफ़ी और नेविगेशन के साथ रेंडर कर सकते हैं।
यह अलगाव ही केंद्रीय विचार है: लेखक छोटे शब्दावली-सेट से अर्थ का वर्णन करते हैं, और गंतव्य तय करता है कि परिणाम कैसा दिखेगा। वही README टर्मिनल, कोड समीक्षा और एक बेहतरीन डॉक्यूमेंटेशन साइट में समान रूप से सुविधाजनक हो सकता है।
# Deploying the API Run the **smoke tests** before release. - Verify health checks - Review error rates - Tag the build
तकनीकी लेखन के लिए मार्कडाउन क्यों उपयुक्त है
मार्कडाउन लेखन और समीक्षा के बीच की दूरी को कम करता है। स्रोत में बहुत कम दृश्य शोर होता है, बदलाव उपयोगी लाइन-आधारित डिफ़ बनाते हैं, और फ़ाइलें उस कोड या कॉन्फ़िगरेशन के बगल में रह सकती हैं जिसकी वे व्याख्या करती हैं।
- पोर्टेबल: सादा टेक्स्ट किसी एक विक्रेता या एडिटर से बंधा नहीं होता।
- डिफ़ेबल: वर्ज़न कंट्रोल में बदलावों की जाँच आसान होती है।
- कंपोज़ेबल: डॉक्यूमेंटेशन टूल इसे HTML, PDF या सहायता सामग्री में बदल सकते हैं।
- पठनीय: रेंडर होने से पहले भी स्रोत उपयोगी होता है।
- स्वचालित: स्क्रिप्ट लिंक, शीर्षकों, उदाहरणों और शैली परंपराओं की जाँच कर सकती हैं।
मार्कडाउन का एक मूल सिंटैक्स और कई रूप होते हैं
सामान्य मूल में पैराग्राफ, शीर्षक, ज़ोर, लिंक, इमेज, ब्लॉककोट, सूचियाँ और कोड शामिल हैं। प्लेटफ़ॉर्म अक्सर एक्सटेंशन जोड़ते हैं। उदाहरण के लिए, GitHub Flavored Markdown ने डेवलपर वर्कफ़्लो में टेबल, टास्क लिस्ट और स्ट्राइकथ्रू को लोकप्रिय बनाया।
एक्सटेंशन उपयोगी हैं, लेकिन पोर्टेबिलिटी अब भी मायने रखती है। एक साधारण शीर्षक लगभग हर जगह काम करता है; एक प्लेटफ़ॉर्म-विशिष्ट डायग्राम ब्लॉक शायद न करे। जब दस्तावेज़ को उपकरणों के बीच जाना हो, तो गंतव्य में सिंटैक्स की जाँच करें और महत्वपूर्ण अर्थ सामान्य टेक्स्ट में रखें।
मार्कडाउन कहाँ दिखाई देता है
मार्कडाउन वहाँ आम है जहाँ सामग्री को सॉफ़्टवेयर के निकट रहना होता है या टेक्स्ट-आधारित वर्कफ़्लो से गुज़रना होता है। यह इंजीनियरिंग के बाहर भी उपयोगी है जब एक टिकाऊ, कम-घर्षण वाला स्रोत सटीक पेज लेआउट से अधिक मूल्यवान होता है।
- README फ़ाइलें, योगदान गाइड, चेंजलॉग और रिलीज़ नोट्स
- API संदर्भ, ट्यूटोरियल, रनबुक और आर्किटेक्चर निर्णय रिकॉर्ड
- इश्यू विवरण, पुल रिक्वेस्ट, टिप्पणियाँ और टीम ज्ञानकोष
- स्टैटिक वेबसाइट, ब्लॉग, उत्पाद डॉक्यूमेंटेशन और आंतरिक हैंडबुक
- नोट्स या परिवर्तित दस्तावेज़ जिन्हें प्रकाशन से पहले सफ़ाई की आवश्यकता होती है
मार्कडाउन किसके लिए डिज़ाइन नहीं किया गया है
मार्कडाउन पेज-लेआउट प्रारूप नहीं है। सटीक फ़ॉन्ट, कॉलम, फ्लोटिंग ऑब्जेक्ट, प्रिंट पेजिनेशन और जटिल इंटरैक्टिव घटक अन्य प्रणालियों की चीज़ें हैं। परिवर्तित PDF या प्रस्तुति अपनी दृश्य रचना की तुलना में उपयोगी टेक्स्ट को अधिक आसानी से सुरक्षित रखेगी।
सादा टेक्स्ट होने मात्र से यह स्वतः सुरक्षित भी नहीं है। रेंडरर को लिंक और वैकल्पिक रॉ HTML को अविश्वसनीय मानना चाहिए। एक अच्छा एडिटर पूर्वावलोकन आउटपुट को सैनिटाइज़ करता है और प्रकाशन पाइपलाइन अपनी सुरक्षा नीति लागू करती है।