Markdown चीटशीट: एक तेज़ और व्यावहारिक ट्यूटोरियल

ज़्यादातर दस्तावेज़ शुरू होते हैं कुछ asterisks और hash signs वाली एक सादी text file से। वह file आम तौर पर Markdown में होती है। यह Web के लिए लिखने का एकमात्र तरीका नहीं है, लेकिन READMEs, issue trackers, chatbots और static sites का default format है, क्योंकि source render होने से पहले भी पढ़ा जा सकता है।

यह पोस्ट एक तेज़ और व्यावहारिक ट्यूटोरियल है। मान लीजिए आपके पास दस मिनट और एक text editor है। कुछ install करने की ज़रूरत नहीं।

Markdown क्या है

Markdown एक हल्की markup syntax है। John Gruber ने 2004 में original spec publish की थी, और उनका एक ही लक्ष्य था: एक ऐसा format जो plain text में अच्छा दिखे और साफ़-साफ़ HTML में बदले। तब से यह GitHub, Obsidian, Notion, कई static site generators और ज़्यादातर large language model outputs का input format बन गया है।

मुख्य विचार सरल है। आप structure को tags की जगह punctuation से mark करते हैं:

# यह एक heading है

यह एक paragraph है।

- यह एक list item है
- यह दूसरा list item है

एक parser इसे HTML में बदलता है। अलग-अलग parser अलग-अलग extensions support करते हैं, और यहीं पर standards मायने रखते हैं।

Markdown standards क्यों मायने रखते हैं

Markdown का कोई एक official standard नहीं है। Gruber की original spec में कुछ खाली जगहें थीं, जिन्हें अलग-अलग tools ने incompatible तरीकों से भरा। अगर आप एक app में table लिखकर दूसरी app में paste करें, तो वह टूट सकती है। आपको पता होना चाहिए कि आप किस dialect को target कर रहे हैं।

CommonMark。 2014 में शुरू हुआ एक strict और अच्छी तरह tested specification। यह core syntax को precisely define करता है। अगर portability चाहिए, तो CommonMark में लिखें।
GitHub Flavored Markdown (GFM)。 Tables, task lists, strikethrough, fenced code blocks और autolinks जोड़ता है। GitHub READMEs और issue comments में यही दिखता है।
Pandoc Markdown。 Citations, footnotes, definition lists, subscripts, superscripts और math जोड़ता है। Academic writing में आम।
Obsidian / Quarto / MDX। Wiki links, callouts, executable code cells या embedded components जोड़ते हैं। Powerful हैं, लेकिन portable नहीं।

रोज़मर्रा के काम के लिए GFM सबसे सुरक्षित target है। ऐसे long documents जो tools के बीच घूम सकते हैं, उनके लिए CommonMark plus documented extension set बेहतर है।

Markdown की बुनियाद

Headings

एक से छह hash signs का इस्तेमाल करें। एक सबसे बड़ा heading है।

# Heading 1

## Heading 2

### Heading 3

Paragraphs और line breaks

Paragraphs को एक blank line से अलग करें। Line के end में दो spaces या backslash लगाकर line break force कर सकते हैं।

यह पहला paragraph है।

यह दूसरा paragraph है।

Emphasis

_italic_ या _italic_
**bold** या **bold**
**_bold और italic_**
~~strikethrough~~ (केवल GFM)

Lists

Unordered lists के लिए -, * या +:

- Item one
- Item two
  - Nested item

Ordered lists के लिए numbers:

1. Step one
2. Step two
3. Step three

Numbers सही होने ज़रूरी नहीं। Render होते समय Markdown उन्हें फिर से number कर देता है। फिर भी source readable रखने के लिए sequential numbers ही लिखें।

Links और images

[Link text](https://example.com)
[Link with title](https://example.com "Title")
![Alt text](https://example.com/image.png)

Internal links के लिए relative paths का इस्तेमाल करें:

[Markdown को PDF में बदलें](/tools/markdown-to-pdf)

Code

Inline code के लिए single backticks: `console.log("hi")`.

Code blocks के लिए triple backticks:

```python
def hello():
    return "hello"
```


Opening backticks के बाद language identifier जोड़ दें ताकि syntax highlighting काम कर सके।

## आम तरकीबें और उदाहरण

### Blockquotes

```markdown
> यह एक quote है।
> यह कई lines तक फैल सकता है।

इन्हें nest भी किया जा सकता है:

> Outer quote
>
> > Nested quote

Horizontal rules

---

एक line में अकेले तीन या ज़्यादा dashes, asterisks या underscores रखें।

Task lists

GFM checkboxes support करता है:

- [x] Draft लिखना
- [ ] Tables चेक करना
- [ ] Post publish करना

ये HTML में disabled checkboxes के रूप में render होते हैं। इन्हें असली form inputs का substitute न बनाएँ।

Characters को escape करना

जब Markdown characters को सीधे दिखाना हो, तो उनके आगे backslash लगाएँ:

\*italic नहीं\*
\# heading नहीं

एडवांस्ड तरकीबें और उदाहरण

Tables

Tables GFM extension हैं, original Markdown spec का हिस्सा नहीं।

| Feature    | CommonMark | GFM |
| ---------- | ---------- | --- |
| Tables     | No         | Yes |
| Task lists | No         | Yes |

Alignment optional है:

| Left | Center | Right |
| :--- | :----: | ----: |
| A    |   B    |     C |

Tables को simple रखें। Nested tables, row spans और column spans standard नहीं हैं और अक्सर fail होते हैं।

Footnotes

Pandoc और कुछ GFM parsers footnotes support करते हैं:

यहाँ एक statement है।[^1]

[^1]: यह footnote text है।

अगर rendered PDF में footnotes चाहिए, तो Pandoc-style syntax support करने वाला converter इस्तेमाल करें या manually embed करें।

Math

Pandoc और कई modern editors LaTeX math support करते हैं:

Inline math: $E = mc^2$

Block math:

$$
\int_a^b f(x) \, dx = F(b) - F(a)
$$

Math rendering parser और output format पर निर्भर करता है। HTML के लिए आमतौर पर MathJax या KaTeX चाहिए। PDF converters को अक्सर LaTeX backend चाहिए।

Definition lists

Pandoc का एक और extension:

Term
: Term की definition।

Another term
: Another definition।

Markdown के अंदर HTML

जब Markdown कम पड़े, तो सीधा HTML लिख सकते हैं:

<p style="color: red;">यह text लाल है।</p>

यह layout, embedded video या ऐसे attributes के लिए काम आता है जो Markdown support नहीं करता। लेकिन यह portability खत्म कर देता है, इसलिए कम ही इस्तेमाल करें।

Markdown को कब convert करें

Markdown लिखने और version control के लिए बेहतरीन है। लेकिन final documents जो हर जगह एक जैसे दिखने चाहिए, उनके लिए यह अच्छा नहीं। इसीलिए converters मौजूद हैं।

अगर आपके पास Markdown draft है जिसे shareable PDF बनाना है, तो Markdown to PDF converter का इस्तेमाल करें। यह browser में चलता है, इसलिए आपकी file आपकी machine से बाहर नहीं जाती।

अगर आपके पास PDF है और editable Markdown चाहिए, तो PDF to Markdown converter का इस्तेमाल करें। यह headings, lists और paragraphs extract करता है, बिना किसी server पर upload किए।