মার্কডাউনকে প্রকাশনা‑প্রস্তুত ফরম্যাটে রূপান্তর

মার্কডাউন ডেভেলপার, লেখক এবং ওপেন‑সোর্স কমিউনিটির জন্য লিঙ্গুয়া ফ্রাঙ্কা হয়ে উঠেছে। এর প্লেইন‑টেক্সট সিনট্যাক্স লিখতে, ভার্সন‑কন্ট্রোল করতে এবং বিভিন্ন প্ল্যাটফর্মে রেন্ডার করতে সহজ। তবুও, বেশিরভাগ দর্শক এখনও সজ্জিত PDF, রেসপন্সিভ 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-এ রূপান্তর

ধাপ ১: একটি LaTeX টেমপ্লেট নির্বাচন করুন

Pandoc PDF আউটপুটের জন্য বেস হিসেবে LaTeX ব্যবহার করে। একটি ভালো টেমপ্লেট মার্জিন, হেডার/ফুটার স্টাইল, ফন্ট এবং কোড‑ব্লক রেন্ডারিং নিয়ন্ত্রণ করে। অফিসিয়াল eisvogel টেমপ্লেটটি জনপ্রিয়, কারণ এটি:

  • listings প্যাকেজের মাধ্যমে সিনট্যাক্স‑হাইলাইটেড কোড ব্লক সমর্থন করে।
  • ক্লিকযোগ্য টেবিল অব কন্টেন্টস (TOC) জেনারেট করে।
  • PDF‑এর XMP প্যাকে মেটাডেটা এমবেড করে, যা ডিজিটাল লাইব্রেরির জন্য সুবিধাজনক।

টেমপ্লেটটি ডাউনলোড করে আপনার অ্যাসেটের পাশে রাখুন।

ধাপ ২: উপযুক্ত ফ্ল্যাগের সঙ্গে 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 কোড ফেন্সের জন্য সঙ্গতিপূর্ণ রঙ নিশ্চিত করে।

ধাপ ৩: ফলাফল যাচাই করুন

PDF খুলে পরীক্ষা করুন:

  • সব হেডিং TOC‑এ সঠিক পেজ নম্বরসহ আছে কিনা।
  • কোড ব্লকগুলো পাঠযোগ্য এবং ভাষা‑নির্দিষ্ট রঙ বজায় রাখে কিনা।
  • ইমেজগুলো এমবেডেড (লিঙ্ক নয়) এবং অনুপাতিকভাবে স্কেল হয়েছে কিনা।
  • মেটাডেটা (লেখক, শিরোনাম) ডকুমেন্ট প্রপার্টি (File → Properties → Description)‑এ দেখা যায় কিনা।

কোনো উপাদান অনুপস্থিত হলে টেমপ্লেট সামঞ্জস্য করুন বা Pandoc ফিল্টার (যেমন, pandoc-citeproc সাইটেশনের জন্য) যোগ করুন।

HTML-এ রূপান্তর

HTML বেশিরভাগ মার্কডাউন ইঞ্জিনের নেটিভ আউটপুট, তবে প্রকাশ‑প্রস্তুত ফলাফলের জন্য অতিরিক্ত ক্লাস ছাড়া সফ্‌ট মার্কআপ দরকার, যা SSG গুলো প্রায়শই ইনজেক্ট করে।

ধাপ ১: মিনিমাল CSS ফ্রেমওয়ার্ক বাছাই করুন

Pure.css বা কাস্টম style.css এর মতো হালকা স্টাইলশিট ব্যবহার করলে পেজ দ্রুত লোড হয় এবং টেবিল, ব্লককোওট এবং কোডের জন্য যুক্তিসঙ্গত ডিফল্ট সরবরাহ করে। CSS ফাইলটি জেনারেটেড HTML-এর একই ডিরেক্টরিতে রাখুন।

ধাপ ২: Pandoc দিয়ে HTML তৈরি করুন

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

--standalone ফ্ল্যাগ বডিকে পূর্ণ HTML ডকুমেন্টে মোড়ায়, আর --toc ন্যাভিগেশন সাইডবার যোগ করে, যা স্টাইলিং করে ফিক্সড পজিশনে রূপান্তর করা যায়।

ধাপ ৩: অ্যাক্সেসিবিলিটি উন্নত করুন

  • <html> ট্যাগে lang="en" যোগ করুন (Pandoc lang=en সেট করলে স্বয়ংক্রিয়ভাবে করে)।
  • সব ইমেজের alt অ্যাট্রিবিউট আছে কিনা নিশ্চিত করুন; যদি আপনার মার্কডাউন এ না থাকে, Pandoc ফিল্টার বা সোর্স এডিটিং দিয়ে যোগ করুন।
  • হেডিং লেভেলগুলো হায়ারার্কিক্যাল কিনা যাচাই করুন (h1 → h2 → h3)।

ধাপ ৪: ব্রাউজারে টেস্ট করুন

output.html Chrome, Firefox ও Edge‑এ খুলুন। কোড ব্লকগুলো সংকীর্ণ ভিউপোর্টে স্ক্রলযোগ্য কিনা এবং TOC সুন্দরভাবে কলাপ্স করে কিনা দেখুন। Chrome DevTools‑এর Lighthouse ব্যবহার করে পারফরম্যান্স ও অ্যাক্সেসিবিলিটি স্কোর চেক করুন।

EPUB (ই‑বুক) এ রূপান্তর

EPUB মূলত XHTML, CSS এবং মেটাডেটা সমন্বিত একটি ZIP আর্কাইভ। Pandoc জটিলতা লুকিয়ে একটি সঠিক প্যাকেজ তৈরি করে।

ধাপ ১: 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>

ধাপ ২: 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 বিভিন্ন ডিভাইসে স্টাইলিং একরূপ করে।

ধাপ ৩: 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 প্যাকেজ প্রয়োজন।
  • 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 ইন্সটলেশন নাও থাকতে পারে বা অস্থায়ী মেশিনে রূপান্তর দরকার হতে পারে। একটি অনলাইন কনভার্টার ভারী কাজগুলো হ্যান্ডল করতে পারে, তবে যদি সার্ভিস ইন‑মেমরি প্রসেস করে এবং ফাইল দীর্ঘ সময় সংরক্ষণ না করে, তাহলে গোপনীয়তা রক্ষা হয়। সাধারণ 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. চাকসাম (Checksum) তুলনা – সোর্স মার্কডাউনের 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 দিয়ে টেক্সটে রূপান্তর করা যায়) তে বানানের ভুল ধরতে পারেন।

এই চেকগুলো CI পাইপলাইনে (GitHub Actions, GitLab CI) অন্তর্ভুক্ত করলে প্রতিটি কমিটে যাচাই করা আউটপুট পাওয়া যাবে।

কর্মপ্রবাহের সারসংক্ষেপ

  1. সোর্স মার্কডাউন ও অ্যাসেট সংগ্রহ। অনুপস্থিত হলে ফ্রন্ট‑মেটার যোগ করুন।
  2. রূপান্তর ইঞ্জিন নির্বাচন (পূর্ণ নিয়ন্ত্রণের জন্য Pandoc সুপারিশ)।
  3. প্রতি টার্গেট ফরম্যাটের জন্য টেমপ্লেট ও CSS কনফিগার করুন।
  4. রূপান্তর কমান্ড চালান – LaTeX‑ভিত্তিক PDF, মিনিমাল স্টাইলশিট সহ HTML, মেটাডেটাসহ EPUB।
  5. আউটপুট যাচাই করুন – চেকসাম, লিঙ্ক ইন্টিগ্রিটি, অ্যাক্সেসিবিলিটি ও ভিজুয়াল ইনস্পেকশন।
  6. Makefile বা CI দিয়ে স্বয়ংক্রিয় করুন যাতে প্রক্রিয়াটি পুনরাবৃত্তি‑যোগ্য থাকে।

এই রেসিপি অনুসরণ করলে একটি মাত্র মার্কডাউন সোর্স থেকে ডেভেলপার গাইড, একাডেমিক হ্যান্ডবুক বা বিতরণের জন্য ই‑বুক সহ সঙ্গতিপূর্ণ, প্রকাশনা‑প্রস্তুত ডকুমেন্ট তৈরি করা সম্ভব।

এখানে বর্ণিত টেকনিকগুলো গোপনীয়তা‑কেন্দ্রিক সার্ভিস যেমন convertise.app‑এর সঙ্গে সামঞ্জস্যপূর্ণ, যা লোকাল টুলস না থাকলে ঐচ্ছিক অন‑ডিমান্ড রূপান্তর এন্ডপয়েন্ট হিসেবে ব্যবহার করা যায়।