मार्कडाउन कोडब्लॉक्स - चीतशीट और उपयोग के उदाहरण

इस लेख में मैं Markdown में कोडब्लॉक विकल्पों का समीक्षा कर रहा हूँ।

Markdown कोड ब्लॉक्स

Markdown कोड ब्लॉक्स Markdown दस्तावेज़ों में कोड या प्रीफॉर्मेटेड टेक्स्ट प्रदर्शित करने का एक तरीका हैं, जो फॉर्मेटिंग को बनाए रखता हैं और विकल्प रूप से सिंटैक्स हाइलाइटिंग की अनुमति देता हैं। Markdown में कोड फॉर्मेटिंग के दो मुख्य प्रकार हैं: इनलाइन कोड और कोड ब्लॉक्स।

Markdown कोड ब्लॉक्स के प्रकार

मुख्य अंतर

• इनलाइन कोड एकल बैक्टिक्स (`) का उपयोग करता हैं और एक वाक्य के भीतर छोटे कोड के लिए हैं।
• इंडेंटेड कोड ब्लॉक्स हर पंक्ति के शुरू में चार स्पेस या एक टैब का उपयोग करते हैं। वे सिंटैक्स हाइलाइटिंग का समर्थन नहीं करते और आधुनिक Markdown में कम आम हैं।
• फेंस्ड कोड ब्लॉक्स ट्रिपल बैक्टिक्स (```) या टिल्ड्स (~~~) को कोड के पहले और बाद में उपयोग करते हैं। यह पसंदीदा विधि है, विशेष रूप से GitHub जैसे प्लेटफॉर्म पर, क्योंकि:
  • वे पढ़ने और लिखने में आसान हैं।
  • आप सिंटैक्स हाइलाइटिंग के लिए ओपनिंग बैक्टिक्स के बाद तुरंत प्रोग्रामिंग भाषा का उल्लेख कर सकते हैं।
  • वे फॉर्मेटिंग को बनाए रखते हैं और मल्टी-लाइन कोड का समर्थन करते हैं।

एक फेंस्ड कोड ब्लॉक के साथ सिंटैक्स हाइलाइटिंग का उदाहरण:

जब हम निम्नलिखित Markdown फॉर्मेटेड टेक्स्ट के साथ होते हैं:

```python
def hello():
    print("Hello, world!")
```

तो रेंडर्ड टेक्स्ट इस प्रकार दिखेगा:

def hello():
    print("Hello, world!")

Markdown कोड ब्लॉक्स का उपयोग करने के लिए सर्वोत्तम प्रथाएँ

• फेंस्ड कोड ब्लॉक्स (ट्रिपल बैक्टिक्स) का उपयोग मल्टी-लाइन कोड के लिए करें ताकि स्पष्टता और प्लेटफॉर्म के बीच संगतता सुनिश्चित हो।
• भाषा का उल्लेख ओपनिंग बैक्टिक्स के बाद सिंटैक्स हाइलाइटिंग के लिए करें (उदाहरण के लिए, ``````python)।
• इनलाइन कोड का उपयोग टेक्स्ट के भीतर छोटे स्निपेट या कमांड्स के लिए करें।
• इंडेंटेड कोड ब्लॉक्स का उपयोग केवल तभी करें जब यह पुराने संगतता के लिए आवश्यक हो, क्योंकि वे सिंटैक्स हाइलाइटिंग का समर्थन नहीं करते और कम पढ़ने योग्य हो सकते हैं।
• फेंस्ड कोड ब्लॉक्स के पहले और बाद में एक खाली पंक्ति रखें ताकि रॉ Markdown में पढ़ने योग्यता सुधारी जा सके।

विशेष सुविधाएँ

• कुछ प्लेटफॉर्म अतिरिक्त भाषा पहचानकर्ताओं जैसे diff का समर्थन करते हैं जो कोड बदलाव दिखाने के लिए उपयोग किए जाते हैं, जो कोड समीक्षा में हटाए गए या जोड़े गए पंक्तियों को हाइलाइट कर सकते हैं।
• कोड ब्लॉक के भीतर बैक्टिक्स प्रदर्शित करने के लिए, ब्लॉक को अधिक बैक्टिक्स से घेरें (उदाहरण के लिए, तीन बैक्टिक्स प्रदर्शित करने के लिए चार बैक्टिक्स का उपयोग करें)।

आउटटेक

सर्वोत्तम पढ़ने योग्यता और सिंटैक्स हाइलाइटिंग के लिए फेंस्ड कोड ब्लॉक्स का उपयोग करें, जिसमें भाषा पहचानकर्ता हो। छोटे स्निपेट के लिए इनलाइन कोड का उपयोग करें, और केवल आवश्यकता पड़ने पर इंडेंटेड ब्लॉक्स का उपयोग करें।

Diff सिंटैक्स हाइलाइटिंग

Markdown कोड ब्लॉक्स में Diff सिंटैक्स हाइलाइटिंग का प्रभावी ढंग से उपयोग करने के लिए, इन चरणों का पालन करें:

• फेंस्ड कोड ब्लॉक्स का उपयोग करें जिसमें ट्रिपल बैक्टिक्स (```) से शुरू और समाप्त करें।
• भाषा पहचानकर्ता के रूप में diff का उल्लेख ओपनिंग बैक्टिक्स के तुरंत बाद करें। यह बदलावों के लिए सिंटैक्स हाइलाइटिंग सक्षम करता है, जो Git कमिट संदेशों या पुल रिक्वेस्ट में देखे गए समान है।

उदाहरण:

- old line that will be removed
+ new line that will be added
 unchanged line

• - से शुरू होने वाली पंक्तियाँ हटाने के रूप में हाइलाइट की जाएंगी (आमतौर पर लाल)।
• + से शुरू होने वाली पंक्तियाँ जोड़ने के रूप में हाइलाइट की जाएंगी (आमतौर पर हरी)।
• प्रीफिक्स के बिना पंक्तियाँ विशेष रूप से हाइलाइट नहीं की जाएंगी।

सर्वोत्तम प्रथाएँ:

• इस प्रारूप का उपयोग करें ताकि दस्तावेज़ीकरण, कोड समीक्षा, या तकनीकी ब्लॉग में कोड बदलाव, सुधार, या सुझाव स्पष्ट रूप से संप्रेषित किए जा सकें।
• अपने कोड ब्लॉक के पहले और बाद में एक खाली पंक्ति रखें ताकि रॉ Markdown में पढ़ने योग्यता बेहतर हो।
• ध्यान दें कि Diff हाइलाइटिंग केवल पूरे पंक्तियों को रंगती है लीडिंग चर के आधार पर; यह पंक्ति के भीतर इनलाइन बदलावों को हाइलाइट नहीं करता।

टिप: इस विधि का समर्थन GitHub, GitLab, और कई Markdown रेंडरर्स जैसे प्लेटफॉर्मों पर व्यापक रूप से किया जाता है, जिससे यह कोड बदलावों को दृश्य रूप से साझा करने के लिए एक विश्वसनीय विकल्प बन जाता है।

समर्थित भाषाएँ

Markdown कोड ब्लॉक्स सिंटैक्स हाइलाइटिंग के लिए एक व्यापक विविधता के भाषाओं का समर्थन करते हैं, लेकिन समर्थित भाषाओं की सटीक सूची उस रेंडरर या प्लेटफॉर्म पर निर्भर करती है जिसे आप उपयोग कर रहे हैं। Markdown स्वयं यह परिभाषित नहीं करता है कि कौन सी भाषाएँ समर्थित हैं; यह केवल भाषा पहचानकर्ता को रेंडरिंग इंजन को पास करता है, जो फिर उपयुक्त सिंटैक्स हाइलाइटिंग लागू करता है। Markdown कोड फेंस स्वयं एक निश्चित सेट के आधिकारिक रूप से समर्थित प्रोग्रामिंग भाषाओं को परिभाषित नहीं करते हैं। इसके बजाय, समर्थित भाषाओं की सूची Markdown रेंडरर या प्लेटफॉर्म पर निर्भर करती है जिसे आप उपयोग कर रहे हैं (जैसे GitHub, GitLab, VS Code, Typora, Quarto, आदि)।

मुख्य प्लेटफॉर्मों (जैसे GitHub, VS Code, Bitbucket, Docusaurus, और ReadMe) पर आमतौर पर समर्थित भाषाएँ शामिल हैं:

• वेब और स्क्रिप्टिंग: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• प्रोग्रामिंग: python (py), java, c, c++, c#, php, ruby, go, rust, scala, swift, kotlin, objective-c
• डेटा और क्वेरी: sql, r, matlab
• मार्कअप और कॉन्फ़िग: markdown, ini, toml, dockerfile, makefile
• विशेष: diff, mermaid, geojson, topojson, stl (GitHub पर डायग्राम और डेटा विज़ुअलाइज़ेशन के लिए)
• अन्य: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme, और बहुत अधिक

भाषा का उल्लेख कैसे करें: ओपनिंग ट्रिपल बैक्टिक्स के तुरंत बाद भाषा का नाम उपयोग करें:

```python
def hello():
    print("Hello, world!")
```

निम्नलिखित भाषाएँ बहुत से Markdown रेंडरर्स में व्यापक रूप से समर्थित हैं:

नोट: वास्तविक पहचानकर्ता भिन्न हो सकता है (उदाहरण के लिए, js vs. javascript)। अधिकांश रेंडरर्स भाषा नामों के लिए केस-इनसेंसिटिव होते हैं।

पूर्ण समर्थित भाषाओं की सूची ढूँढना:

• GitHub: Linguist का उपयोग हाइलाइटिंग के लिए करता है, जिसमें हजारों भाषाओं का समर्थन करता है।
• VS Code & कई वेब रेंडरर्स: highlight.js या Pygments का उपयोग करते हैं—उनके दस्तावेज़ीकरण के लिए व्यापक सूचियाँ देखें।
• Bitbucket: CodeMirror modes और Pygments lexers का संदर्भ देता है।

मुख्य बिंदु:

• अधिकांश प्लेटफॉर्म सभी प्रमुख प्रोग्रामिंग, स्क्रिप्टिंग, और मार्कअप भाषाओं का समर्थन करते हैं।
• कुछ प्लेटफॉर्म डायग्राम और डेटा फॉर्मेट (जैसे mermaid, geojson) का भी समर्थन करते हैं।
• भाषा पहचानकर्ता आमतौर पर केस-इनसेंसिटिव होता है लेकिन सर्वोत्तम संगतता के लिए लोअर केस में होना चाहिए।
• अगर आप एक असमर्थित भाषा पहचानकर्ता का उपयोग करते हैं, तो कोड ब्लॉक प्लेन टेक्स्ट के रूप में रेंडर होगा।

मार्कडाउन कोड ब्लॉक में फाइलनाम निर्दिष्ट करना

मार्कडाउन कोड ब्लॉक में फाइलनाम निर्दिष्ट करने के लिए कई विकल्प हैं, लेकिन विधि प्लेटफॉर्म और रेंडरर पर निर्भर करती है:

1. कोड ब्लॉक लेबल में फाइलनाम (मेटा सिंटैक्स)

कुछ मार्कडाउन इंजन (जैसे कुछ स्टैटिक साइट जनरेटर, दस्तावेज़ीकरण टूल्स, और ब्लॉगिंग प्लेटफॉर्म) एक मेटा सिंटैक्स का समर्थन करते हैं जहां आप भाषा के बाद कोलन (:) के बाद फाइलनाम जोड़ते हैं:

```js:app.js
console.log("Hello, world!");
```

यह कोड ब्लॉक के ऊपर या साथ में फाइलनाम (जैसे, app.js) प्रदर्शित करेगा, रेंडरर पर निर्भर करते हुए। और इस वेबसाइट का ह्यूगो रेंडरर ऐसा नहीं करता:

console.log("Hello, world!");

नोट: यह सभी प्लेटफॉर्म पर समर्थित नहीं है (उदाहरण के लिए, GitHub-flavored Markdown वर्तमान में इस फीचर का समर्थन नहीं करता है)।

2. मैनुअल फाइलनाम हेडिंग या इनलाइन कोड

सर्वव्यापी संगतता के लिए (GitHub, Stack Overflow, और अधिकांश मार्कडाउन रेंडरर सहित), कोड ब्लॉक के ऊपर फाइलनाम रखें, एक हेडिंग या बोल्ड इनलाइन कोड का उपयोग करके:

**`app.js`**

```
console.log("Hello, world!");
```

या:

#### `app.js`

```
console.log("Hello, world!");
```

यह फाइलनाम को कोड ब्लॉक से दृश्य रूप से जुड़ता है और हर जगह काम करता है।

3. कोड के अंदर फाइलनाम को एक टिप्पणी के रूप में शामिल करना

अल्टरनेटिव रूप से, आप कोड ब्लॉक के अंदर फाइलनाम को एक टिप्पणी के रूप में शामिल कर सकते हैं:

```
// app.js
console.log("Hello, world!");
```

यह विशेष रूप से उपयोगी है अगर आप चाहते हैं कि फाइलनाम कोड को कॉपी करने पर दिखाई दे।

सारांश और सर्वोत्तम अभ्यास

सर्वोत्तम संगतता के लिए कोड ब्लॉक के ऊपर एक हेडिंग या बोल्ड इनलाइन कोड का उपयोग करें, और विभिन्न प्लेटफॉर्म पर साझा करने पर स्पष्टता के लिए कोड के अंदर एक टिप्पणी जोड़ने का विचार करें।

उपयोगी लिंक

• Markdown Cheatsheet - सबसे उपयोगी संरचनाएं और कमांड्स
• Hugo Cheat Sheet
• Bash Cheat Sheet - सबसे उपयोगी बाश कमांड्स
• LaTeX Cheat Sheet
• Hugo के लिए सबसे लोकप्रिय थीम्स
• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks