मार्कडाउन को प्रकाशन‑तैयार स्वरूपों में बदलना

मार्कडाउन डेवलपर्स, लेखकों और ओपन‑सोर्स समुदायों की भाषा बन चुकी है। इसकी साधारण‑पाठ सिंटैक्स लिखने, संस्करण‑नियंत्रण करने और विभिन्न प्लेटफ़ॉर्म पर रेंडर करने में आसान है। फिर भी, अधिकांश दर्शक अभी भी परिष्कृत PDFs, रेस्पॉन्सिव HTML पेज या EPUB ई‑बुक की उम्मीद करते हैं। इन डाउनस्ट्रीम फ़ॉर्मेट्स में मार्कडाउन को बदलना—हेडिंग, टेबल, कोड ब्लॉक या मेटाडेटा खोए बिना—काफी कठिन हो सकता है। नीचे दिया गया गाइड एक पुनरुत्पादनीय वर्कफ़्लो प्रस्तुत करता है जो फ़िडेलिटी, प्रदर्शन और गोपनीयता के बीच संतुलन बनाता है।

स्रोत सामग्री को समझना

किसी भी रूपांतरण से पहले, मार्कडाउन फ़ाइल को एक स्रोत दस्तावेज़ मानें, न कि अंतिम उत्पाद। उन तत्वों की पहचान करें जिन्हें विशेष देखभाल चाहिए:

  • फ़्रंट‑मैटर मेटाडेटा (शीर्षक, लेखक, तिथि, टैग)। कई स्थैतिक‑साइट जेनरेटर में यह YAML के रूप में --- से सीमित दिखता है। इसे रख‑रखाव करें क्योंकि डाउनस्ट्रीम फ़ॉर्मेट्स अक्सर कवर पेज या एम्बेडेड मेटाडेटा के लिए इसका उपयोग करते हैं।
  • कोड फ़ेंस जिनमें भाषा पहचानकर्ता हों। सिंटैक्स हाइलाइटिंग को रूपांतरण के बाद भी बरकरार रहना चाहिए, विशेषकर तकनीकी पुस्तकों के लिए।
  • टेबल, फ़ुटनोट और डिफ़िनिशन लिस्ट। सभी लक्ष्य फ़ॉर्मेट्स इन्हें मूल रूप में सपोर्ट नहीं करते; आपको इन्हें HTML <table> या PDF टेबल स्ट्रक्चर में मैप करना पड़ सकता है।
  • छवियाँ और एसेट्स जो सापेक्ष पाथ से रेफ़र किए गए हैं। एक रूपांतरण पाइपलाइन को ये पाथ हल करने और वैकल्पिक रूप से बाइनरी डेटा एम्बेड करने की ज़रूरत होती है।
  • आंतरिक लिंक (जैसे [Section](#section)) और क्रॉस‑डॉक्यूमेंट रेफ़रेंसेज़। जब एकल PDF या EPUB बनाते हैं, तो इन्हें कार्यात्मक बुकमार्क या हाइपरलिंक में बदलना चाहिए।

इन पहलुओं को पहले ही सूचीबद्ध करके आप बाद में पाइपलाइन में आश्चर्य से बच सकते हैं।

सही रूपांतरण इंजन का चयन

मार्कडाउन के लिए तीन प्रमुख प्रकार के कॉनवर्टर्स हैं:

  1. Pandoc‑आधारित पाइपलाइन – Pandoc एक सार्वभौमिक डॉक्यूमेंट कॉनवर्टर है जो मार्कडाउन पढ़ सकता है और PDF, HTML, EPUB, DOCX आदि कई फ़ॉर्मेट में आउटपुट कर सकता है। यह साइटेशन, फ़ुटनोट और कस्टम टेम्पलेट्स को संभालने में उत्कृष्ट है।
  2. स्थैतिक‑साइट जेनरेटर (SSG) – Hugo, Jekyll, या MkDocs जैसे टूल मार्कडाउन को HTML में रेंडर करते हैं और थीमिंग सिस्टम प्रदान करते हैं। यह पूर्ण‑फ़ीचर वाली वेबसाइट के लिए उपयुक्त है, लेकिन इसे हेडलेस प्रिंट टूल्स के साथ भी जोड़ा जा सकता है।
  3. वेब‑आधारित सेवाएँ – convertise.app जैसी प्लेटफ़ॉर्म एक REST एन्डपॉइंट प्रदान करती हैं जो मार्कडाउन फ़ाइल लेती हैं और इच्छित आउटपुट फ़ॉर्मेट लौटाती हैं। यह बिना सॉफ़्टवेयर स्थापित किए एक‑बार के रूपांतरण के लिए उपयोगी है।

एक दोहराएँ योग्य, गोपनीयता‑पहले वर्कफ़्लो के लिए, स्थानीय Pandoc इंस्टॉलेशन की सलाह दी जाती है। यह पूरी तरह उपयोगकर्ता के मशीन पर चलता है, दूरस्थ सर्वर पर कोई निशान नहीं छोड़ता।

पर्यावरण तैयार करना

  1. Pandoc स्थापित करें (नवीनतम स्थिर संस्करण) और यदि आप PDF जनरेट करना चाहते हैं तो एक LaTeX डिस्ट्रिब्यूशन (जैसे TinyTeX) भी स्थापित करें।
  2. वर्चुअल एनवायरनमेंट सेट अप करें (Python venv या Node nvm) ताकि सहायक टूल्स अलग‑अलग रहें।
  3. एसेट इकट्ठा करें – सभी रेफ़र की गई इमेज, PDF और फ़ॉन्ट फ़ाइलों को एक फ़ोल्डर में कॉपी करें। इससे कॉनवर्टर के लिए पाथ हल करना बेहद आसान हो जाता है।
  4. मेटाडेटा फ़ाइल बनायें – यदि आपके मार्कडाउन में फ़्रंट‑मैटर नहीं है, तो metadata.yaml नाम की छोटी फ़ाइल बनाये जिसमें title, author, date और अन्य आवश्यक फ़ील्ड हों।
---
title: "Effective Open‑Source Documentation"
author: "Jane Doe"
date: "2026-05-10"
keywords: [markdown, documentation, publishing]
---

आप इस ब्लॉक को हर स्रोत फ़ाइल के आगे जोड़ सकते हैं या Pandoc को --metadata-file के ज़रिए पास कर सकते हैं।

PDF में बदलना

चरण 1: LaTeX टेम्पलेट चुनें

PDF आउटपुट के लिए Pandoc आंतरिक रूप से LaTeX का उपयोग करता है। एक अच्छी तरह से तैयार टेम्पलेट मार्जिन, हेडर/फ़ूटर शैली, फ़ॉन्ट और कोड‑ब्लॉक रेंडरिंग को नियंत्रित करता है। आधिकारिक eisvogel टेम्पलेट लोकप्रिय है क्योंकि यह:

  • listings पैकेज के साथ सिंटैक्स‑हाइलाइटेड कोड ब्लॉक सपोर्ट करता है।
  • क्लिक‑योग्य टेबल ऑफ़ कंटेंट्स जेनरेट करता है।
  • PDF के XMP पैकेट में मेटाडेटा एम्बेड करता है, जो डिजिटल लाइब्रेरीज़ के लिये उपयोगी है।

टेम्पलेट डाउनलोड करके अपने एसेट्स के पास रख दें।

चरण 2: उपयुक्त फ़्लैग के साथ Pandoc चलाएँ

pandoc main.md \
  --metadata-file=metadata.yaml \
  --template=eisvogel.tex \
  --toc \
  --highlight-style=pygments \
  --pdf-engine=xelatex \
  -V mainfont="Libre Baskerville" \
  -V monofont="Fira Code" \
  -o output.pdf

मुख्य विकल्पों की व्याख्या

  • --toc स्वचालित रूप से टेबल ऑफ़ कंटेंट बनाता है।
  • -V mainfont और -V monofont यह सुनिश्चित करते हैं कि PDF आपके वांछित विज़ुअल आइडेंटिटी को बरकरार रखे।
  • --highlight-style कोड फ़ेंस के लिये स्थिर रंग प्रदान करता है।

चरण 3: परिणाम की जाँच करें

PDF खोलें और जांचें:

  • सभी हेडिंग टेबल‑ऑफ़‑कंटेंट में सही पेज नंबर के साथ दिखें।
  • कोड ब्लॉक पठनीय हों और भाषा‑विशिष्ट रंग बरकरार रहें।
  • इमेज एम्बेडेड हों (लिंक नहीं) और अनुपातिक रूप से स्केल हों।
  • मेटाडेटा (लेखक, शीर्षक) डॉक्यूमेंट प्रॉपर्टीज़ में दिखे (File → Properties → Description)।

यदि कोई तत्व गायब है, तो टेम्पलेट को समायोजित करें या Pandoc फ़िल्टर (जैसे pandoc-citeproc साइटेशन के लिये) जोड़ें।

HTML में बदलना

HTML अधिकांश मार्कडाउन इंजनों का मूल आउटपुट है, पर प्रकाशन‑तैयार परिणाम के लिये आपको साफ‑सुथरा मार्कअप चाहिए, बिना उन अतिरिक्त क्लासेज़ के जो SSG जोड़ते हैं।

चरण 1: न्यूनतम CSS फ्रेमवर्क चुनें

एक हल्की स्टाइलशीट जैसे Pure.css या स्वयं निर्मित style.css पेज को तेज़ रखती है और टेबल, ब्लॉकक़ोट और कोड के लिये उपयुक्त डिफ़ॉल्ट देता है। CSS फ़ाइल को जेनरेटेड HTML के समान डायरेक्टरी में रखें।

चरण 2: Pandoc से HTML जनरेट करें

pandoc main.md \
  --metadata-file=metadata.yaml \
  --standalone \
  --toc \
  --css=style.css \
  --highlight-style=pygments \
  -o output.html

--standalone फ़्लैग बॉडी को पूर्ण HTML डॉक्यूमेंट में लपेटता है, जबकि --toc नेविगेशन साइडबार जोड़ता है जिसे आप स्थिर पोज़िशन में स्टाइल कर सकते हैं।

चरण 3: एक्सेसिबिलिटी बढ़ाएँ

  • <html> टैग में lang="en" जोड़ें (Pandoc स्वचालित रूप से lang=en सेट करता है)।
  • सभी इमेज में alt एट्रिब्यूट हों; यदि आपका मार्कडाउन इन्हें छोड़ता है, तो Pandoc फ़िल्टर या स्रोत को संपादित करके जोड़ें।
  • हेडिंग लेवल्स हायरार्किकल रहें (h1 → h2 → h3)।

चरण 4: ब्राउज़र में परीक्षण करें

output.html को Chrome, Firefox और Edge में खोलें। देखें कि कोड ब्लॉक संकीर्ण व्यूपोर्ट पर स्क्रॉलेबल हैं और टेबल‑ऑफ़‑कंटेंट सुगमता से कोलेप्स हो रहा है। Chrome DevTools के Lighthouse से पेज के प्रदर्शन और एक्सेसिबिलिटी स्कोर की पुष्टि करें।

EPUB (ई‑बुक) में बदलना

EPUB मूलतः XHTML, CSS और मेटाडेटा का ZIP आर्काइव है। Pandoc इस जटिलता को छुपा कर एक साफ़ पैकेज बनाता है।

चरण 1: EPUB मेटाडेटा को फाइन‑ट्यून करें

Pandoc के --epub-metadata फ़्लैग से ID, प्रकाशक और भाषा की जानकारी एम्बेड की जा सकती है। सरल epub-metadata.xml बनायें:

<?xml version="1.0" encoding="UTF-8"?>
<dc:metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
  <dc:title>Effective Open‑Source Documentation</dc:title>
  <dc:creator>Jane Doe</dc:creator>
  <dc:language>en</dc:language>
  <dc:identifier id="bookid" opf:scheme="ISBN">978-3-16-148410-0</dc:identifier>
  <dc:publisher>Self‑Published</dc:publisher>
</dc:metadata>

चरण 2: EPUB विकल्पों के साथ Pandoc चलाएँ

pandoc main.md \
  --metadata-file=metadata.yaml \
  --epub-metadata=epub-metadata.xml \
  --toc \
  --css=style.css \
  --highlight-style=pygments \
  -o book.epub

टेबल‑ऑफ़‑कंटेंट ई‑बुक के नेविगेशन फ़ाइल बन जाएगा, और CSS विभिन्न डिवाइसेज़ पर समान स्टाइलिंग सुनिश्चित करेगा।

चरण 3: EPUB को वैलिडेट करें

epubcheck (एक ओपन‑सोर्स वैलिडेटर) का उपयोग करके टूटे लिंक, गायब इमेज या गलत XHTML की जाँच करें:

java -jar epubcheck.jar book.epub

रिपोर्टेड समस्याओं को ठीक करें, फिर फ़ाइल को रीडर्स को वितरित या Kindle Direct Publishing जैसी प्लेटफ़ॉर्म पर अपलोड करें।

एसेट एम्बेडिंग और पाथ रिज़ॉल्यूशन का हैंडलिंग

मार्कडाउन अक्सर इमेज को सापेक्ष पाथ (![](images/logo.png)) से रेफ़र करता है। रूपांतरण के दौरान आपको इन एसेट्स को एम्बेड करना पड़ सकता है, खासकर PDF और EPUB के लिये।

  • Pandoc का --resource-path विकल्प यह बताता है कि एसेट्स कहां खोजे जाएँ।
  • --extract-media=./media फ़्लैग किसी भी लिंक्ड मीडिया को media फ़ोल्डर में कॉपी करता है और मार्कअप को उन कॉपीज़ की ओर पुनः लिखता है।
  • PDF के लिये, LaTeX उपयोग करते हुए --pdf-engine-opt=--shell-escape विकल्प बाहरी फ़ाइलों को शामिल करने की अनुमति देता है।

यदि आप एक‑फ़ाइल वाला आउटपुट (जैसे सेल्फ‑कंटेंडेड HTML) चाहते हैं, तो पोस्ट‑प्रोसेसिंग में pandoc --self-contained या wget --convert-links जैसे टूल इस्तेमाल करें।

सभी फ़ॉर्मेट्स में कोड हाइलाइटिंग को संरक्षित करना

डेवलपर‑केन्द्रित डॉक्यूमेंटेशन में सतत सिंटैक्स हाइलाइटिंग बहुत महत्वपूर्ण है।

  • Pandoc कई हाइलाइट स्टाइल सपोर्ट करता है (pygments, kate, tango)। ऐसा चुनें जो PDF और HTML दोनों में अच्छा दिखे।
  • PDF के लिये, Pandoc हाइलाइटिंग को LaTeX listings या minted में बदलता है। minted उपयोग करने के लिये --pdf-engine-opt=-shell-escape फ़्लैग और pygments Python पैकेज आवश्यक है।
  • EPUB में, हाइलाइटिंग को इन‑लाइन CSS स्पैन्स (<span class="hlkwd">) के रूप में रेंडर किया जाता है। CSS फ़ाइल में संबंधित स्टाइल नियम होने चाहिए।

यदि आपको कस्टम कलर स्कीम चाहिए, तो pygmentize -S <style> -f html -a .code से स्टाइल फ़ाइल बनाकर अपने CSS में शामिल कर सकते हैं।

Makefile से वर्कफ़्लो ऑटोमेट करना

एक ही कमांड को हर फ़ॉर्मेट के लिये दोहराना त्रुटिपूर्ण हो सकता है। एक साधारण Makefile पुनरुत्पादनीयता सुनिश्चित करता है:

SOURCES = main.md metadata.yaml
ASSETS  = $(wildcard images/*)

PDF    = output.pdf
HTML   = output.html
EPUB   = book.epub

all: $(PDF) $(HTML) $(EPUB)

$(PDF): $(SOURCES) $(ASSETS)
	pandoc $$(filter %.md,$^) \
	  --metadata-file=metadata.yaml \
	  --template=eisvogel.tex \
	  --toc \
	  --highlight-style=pygments \
	  --pdf-engine=xelatex \
	  -V mainfont="Libre Baskerville" \
	  -V monofont="Fira Code" \
	  -o $@

$(HTML): $(SOURCES) $(ASSETS)
	pandoc $$(filter %.md,$^) \
	  --metadata-file=metadata.yaml \
	  --standalone \
	  --toc \
	  --css=style.css \
	  --highlight-style=pygments \
	  -o $@

$(EPUB): $(SOURCES) $(ASSETS)
	pandoc $$(filter %.md,$^) \
	  --metadata-file=metadata.yaml \
	  --epub-metadata=epub-metadata.xml \
	  --toc \
	  --css=style.css \
	  --highlight-style=pygments \
	  -o $@

clean:
	rm -f $(PDF) $(HTML) $(EPUB)

अब make चलाने से सभी तीन आउटपुट एक ही कमांड से बनेंगे, और यह सुनिश्चित होगा कि हर फ़ॉर्मेट समान स्रोत फ़ाइलों से उत्पन्न हो।

कब क्लाउड सेवा जैसे convertise.app का उपयोग करें

कुछ स्थितियों में आपके पास स्थानीय LaTeX इंस्टॉलेशन नहीं हो सकता या आप अस्थायी मशीन पर फ़ाइल बदलना चाहते हों। ऑनलाइन कॉनवर्टर भारी काम को संभाल सकता है, बशर्ते वह डेटा इन‑मैमर्y प्रोसेस करे और फ़ाइलें दीर्घकालिक न रखे। एक सामान्य POST रिक्वेस्ट का उदाहरण इस प्रकार है:

POST https://convertise.app/api/convert
Content-Type: multipart/form-data

---
Content-Disposition: form-data; name="file"; filename="main.md"
Content-Type: text/markdown

<Markdown content>
---
Content-Disposition: form-data; name="target"

pdf
---

जवाब में परिवर्तित PDF बाइनरी स्ट्रीम के रूप में मिलेगा। यह एक‑बार के कार्यों के लिये अच्छा है, पर दोहराने योग्य प्रकाशन पाइपलाइन के लिये स्थानीय Pandoc समाधान अभी भी सबसे पारदर्शी और ऑडिटेबल रहता है।

फ़ॉर्मेट्स के बीच फ़िडेलिटी की टेस्टिंग

रूपांतरण के बाद, इन स्वचालित जांचों को चलाएँ:

  1. चेकसम तुलना – स्रोत Markdown का SHA‑256 हैश बनाकर आउटपुट फ़ाइलों के साथ रखें। इससे पुष्टि होती है कि बिल्ड के बीच स्रोत नहीं बदला।
  2. लिंक वैलिडेशन – pandoc --filter pandoc-citeproc से सुनिश्चित करें कि सभी आंतरिक रेफ़रेंसेज़ हल हों।
  3. इमेज रास्टराइज़ेशन टेस्ट – PDF और EPUB को अलग‑अलग व्यूअर में खोलें, यह जाँचें कि इमेज इच्छित DPI (प्रिंट के लिये आमतौर पर 300 dpi, स्क्रीन के लिये 72 dpi) से नीचे नहीं गयी।
  4. एक्सेसिबिलिटी ऑडिट – PDF के लिये pdfaPilot या HTML के लिये axe-core जैसे टूल गायब alt‑टेक्स्ट या गलत हेडिंग ऑर्डर का पता लगाते हैं।
  5. स्पेल‑चेक – aspell या hunspell को जनरेटेड HTML या PDF (जैसे pdftotext से extracted टेक्स्ट) पर चलाकर फ़िल्टर‑भूलों को पकड़ें।

इन चेक्स को CI पाइपलाइन (GitHub Actions, GitLab CI) में शामिल करने से हर कमिट पर एक सत्यापित प्रकाशित एसेट सेट बनता है।

वर्कफ़्लो सारांश

  1. स्रोत Markdown और एसेट्स इकट्ठा करें। यदि आवश्यक हो तो फ़्रंट‑मैटर जोड़ें।
  2. रूपांतरण इंजन चुनें (पूर्ण नियंत्रण के लिये Pandoc सुझाया गया)।
  3. प्रत्येक लक्ष्य फ़ॉर्मेट के लिये टेम्पलेट और CSS कॉन्फ़िगर करें।
  4. रूपांतरण कमांड चलाएँ – PDF के लिये LaTeX, HTML के लिये न्यूनतम स्टाइलशीट, EPUB के लिये मेटाडेटा।
  5. आउटपुट वैलिडेट करें – चेकसम, लिंक इंटीग्रिटी, एक्सेसिबिलिटी और विज़ुअल इंस्पेक्शन।
  6. Makefile या CI के साथ ऑटोमेट करें ताकि प्रक्रिया दोहराने योग्य रहे।

इस विधि का पालन करके आप एक ही मार्कडाउन स्रोत से लगातार, प्रकाशन‑तैयार दस्तावेज़ बना सकते हैं—चाहे वह डेवलपर गाइड हो, अकादमिक हैंडबुक हो या वितरण‑योग्य ई‑बुक।

यहाँ वर्णित तकनीकें गोपनीयता‑केन्द्रित सेवाओं जैसे convertise.app के साथ संगत हैं, जिन्हें स्थानीय टूलिंग उपलब्ध न होने पर वैकल्पिक ऑन‑डिमांड कॉनवर्ज़न एन्डपॉइंट के रूप में इस्तेमाल किया जा सकता है।