تبدیل مارک‌داون به فرمت‌های آماده انتشار

مارک‌داون تبدیل به زبان مشترک برای توسعه‌دهندگان، نویسندگان و جوامع متن‌باز شده است. سینتکس متنی آن نوشتن، کنترل نسخه و رندر در سرتاسر پلتفرم‌ها را آسان می‌سازد. با این حال، اکثر مخاطبان هنوز انتظار خروجی‌های PDF تمیز، صفحات HTML واکنش‌گرا یا کتاب‌های الکترونیکی EPUB را دارند. تبدیل مارک‌داون به این فرمت‌های پایین‌دستی بدون از دست دادن عناوین، جدول‌ها، بلوک‌های کد یا متادیتا می‌تواند به‌صرفه‌جویی عجیب باشد. راهنمای زیر جریان کاری تکرارپذیری را که بین صحت، کارایی و حریم خصوصی تعادل برقرار می‌کند، مرور می‌کند.

درک مواد منبع

قبل از هر تبدیل، فایل مارک‌داون را به‌عنوان سند منبع نه یک محصول نهایی در نظر بگیرید. عناصر نیازمند پردازش خاص را شناسایی کنید:

  • متادیتای Front‑matter (عنوان، نویسنده، تاریخ، برچسب‌ها). در بسیاری از ژنراتورهای سایت استاتیک این بخش به‌صورت YAML بین --- ظاهر می‌شود. آن را حفظ کنید چون فرمت‌های پایین‌دستی اغلب برای صفحه‌کاور یا متادیتای توکار به این اطلاعات نیاز دارند.
  • قاب‌های کد با شناساگر زبان. برجسته‌سازی سینتکس باید در تبدیل حفظ شود، به‌ویژه برای کتاب‌های فنی.
  • جدول‌ها، پاورقی‌ها و فهرست‌های تعریف. همهٔ فرمت‌های هدف به‌صورت بومی از آنها پشتیبانی نمی‌کنند؛ ممکن است نیاز باشد آنها را به <table> HTML یا ساختارهای جدول PDF تبدیل کنید.
  • تصاویر و دارایی‌ها که با مسیرهای نسبی ارجاع داده می‌شوند. یک خط لوله تبدیل باید آن مسیرها را حل کند و به‌صورت دلخواه داده‌باینری را جاسازی کند.
  • پیوندهای داخلی (مثلاً [بخش](#section)) و ارجاعات میان‌سندی. هنگام تولید یک PDF یا EPUB تک‌فایل، این‌ها باید به بوکمارک یا ابرلینکهای کارا تبدیل شوند.

با فهرست کردن این جنبه‌ها در اوایل، از شگفتی‌های بعدی در خط لوله جلوگیری می‌کنید.

انتخاب موتور تبدیل مناسب

سه خانوادهٔ کلی از مبدل‌های مارک‌داون وجود دارد:

  1. خط لوله‌های مبتنی بر Pandoc – پانداک یک مبدل جهان‌شمول است که می‌تواند مارک‌داون را بخواند و PDF، HTML، EPUB، DOCX و بسیاری فرمت‌های دیگر را خروجی بدهد. در مدیریت استنادات، پاورقی‌ها و قالب‌های سفارشی برتری دارد.
  2. ژنراتورهای سایت ایستیک (SSG) – ابزارهایی چون Hugo، Jekyll یا MkDocs مارک‌داون را به HTML با سیستم‌های تمینگ رندر می‌کنند. برای وب‌سایت‌های کامل ایده‌آل‌اند ولی می‌توانند با ابزارهای چاپ سرسری ترکیب شوند.
  3. سرویس‌های مبتنی بر وب – پلتفرم‌هایی مانند convertise.app نقطهٔ پایانی RESTی را عرضه می‌کنند که یک فایل مارک‌داون می‌گیرد و فرمت خروجی انتخاب‌شده را برمی‌گرداند. برای تبدیل‌های یک‌بار بدون نصب نرم‌افزار مفیدند.

برای یک جریان کاری تکرارپذیر و اولویت‌دار حریم‌خصوصی، نصب محلی Pandoc توصیه می‌شود. این ابزار کاملاً روی دستگاه کاربر اجرا می‌شود و هیچ ردپایی روی سرورهای راه‌دور باقی نمی‌گذارد.

آماده‌سازی محیط

  1. Pandoc (آخرین نسخهٔ پایدار) و یک توزیع LaTeX (مثلاً TinyTeX) را نصب کنید اگر قصد دارید PDF تولید کنید.
  2. یک محیط مجازی (Python venv یا Node nvm) تنظیم کنید تا ابزارهای کمکی درIsolation بمانند.
  3. دارایی‌ها را جمع‌آوری کنید – تمام تصاویر، PDFها و فایل‌های فونت مورد ارجاع را در یک پوشهٔ واحد کپی کنید. این کار برای حل مسیرها برای مبدل ساده می‌شود.
  4. یک فایل متادیتا ایجاد کنید – اگر مارک‌داون شما فاقد Front‑matter است، یک metadata.yaml کوچک بنویسید که شامل title، author، date و هر فیلد دیگری که می‌خواهید جاسازی شود.
---
title: "مستندسازی باز‑منبع مؤثر"
author: "جین دو"
date: "2026-05-10"
keywords: [markdown, documentation, publishing]
---

می‌توانید این بلاک را به هر فایل منبع اضافه کنید یا با --metadata-file به پانداک بدهید.

تبدیل به PDF

گام 1: انتخاب یک قالب LaTeX

Pandoc برای خروجی PDF از LaTeX استفاده می‌کند. یک قالب خوب حاشیه‌ها، سبک سرصفحه/پاورقی، فونت‌ها و رندر بلوک‌های کد را کنترل می‌کند. قالب رسمی eisvogel به‌خاطر موارد زیر محبوب است:

  • پشتیبانی از بلوک‌های کد برجسته‌شده با بسته listings.
  • تولید فهرست مطالب قابل کلیک.
  • جاسازی متادیتا در بستهٔ XMP PDF که برای کتابخانه‌های دیجیتال مفید است.

قالب را دانلود کنید و در کنار دارایی‌هایتان قرار دهید.

گام 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 خروجی بومی اکثر موتورهای مارک‌داون است، اما برای خروجی آماده انتشار نیاز به یک markup تمیز بدون کلاس‌های اضافه‌ای که SSGها تزریق می‌کنند، دارید.

گام 1: انتخاب یک چارچوب CSS کمینه

یک stylesheet سبک مانند Pure.css یا یک style.css سفارشی صفحه را سریع نگه می‌دارد و پیش‌فرض‌های معقولی برای جدول‌ها، بلوک‌اقتباس و کد فراهم می‌کند. فایل CSS را در همان پوشهٔ HTML تولیدشده نگه دارید.

گام 2: تولید HTML با Pandoc

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 باز کنید. بررسی کنید که بلوک‌های کد در صفحه‌های باریک قابل اسکرول هستند و فهرست مطالب به‌نرمی جمع می‌شود. از Lighthouse (در Chrome DevTools) برای اطمینان از امتیاز خوب عملکرد و دسترس‌پذیری استفاده کنید.

تبدیل به EPUB (کتاب الکترونیکی)

EPUB در واقع یک آرشیو ZIP شامل XHTML، CSS و متادیتا است. Pandoc پیچیدگی را مخفی می‌کند و یک بستهٔ مرتب می‌سازد.

گام 1: تنظیم دقیق متادیتای EPUB

از پرچم --epub-metadata پانداک برای جاسازی شناسه، ناشر و زبان استفاده کنید. یک فایل سادهٔ epub-metadata.xml بسازید:

<?xml version="1.0" encoding="UTF-8"?>
<dc:metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
  <dc:title>مستندسازی باز‑منبع مؤثر</dc:title>
  <dc:creator>جین دو</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: اجرای Pandoc با گزینه‌های EPUB

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 کپی می‌کند و markup را به‌روزرسانی می‌کند تا به این کپی‌ها اشاره کند.
  • برای PDF، گزینهٔ --pdf-engine-opt=--shell-escape (در هنگام استفاده از LaTeX) به موتور اجازه می‌دهد فایل‌های خارجی را بگنجاند.

اگر خروجی تک‑فایلی می‌خواهید (مثلاً HTML خود‑حاوی)، از گام پردازش پس‌از با pandoc --self-contained یا ابزار بیرونی مثل wget --convert-links استفاده کنید.

حفظ برجسته‌سازی کد در تمام فرمت‌ها

برجسته‌سازی یکسان برای مستندات متمرکز بر توسعه‌دهندگان حیاتی است.

  • Pandoc استایل‌های برجسته‌سازی متعددی (pygments, kate, tango) را پشتیبانی می‌کند. یکی را انتخاب کنید که هم در PDF و هم در HTML خوب به‌نظر برسد.
  • برای PDF، Pandoc برجسته‌سازی را به LaTeX listings یا minted ترجمه می‌کند. minted به پرچم --pdf-engine-opt=-shell-escape و بستهٔ Python pygments نیاز دارد.
  • برای EPUB، برجسته‌سازی به‌صورت <span class="hlkwd">های CSS داخلی رندر می‌شود. فایل 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

<محتوای مارک‌داون>
---
Content-Disposition: form-data; name="target"

pdf
---

پاسخ PDF تبدیل‌شده را به‌صورت یک جریان باینری برمی‌گرداند. این روش برای وظایف یک‌بار مناسب است، اما برای خطوط کاری قابل تکرار انتشار، راه‌حل محلی Pandoc همچنان شفاف‌ترین و قابل حسابرسی‌ترین گزینه باقی می‌ماند.

آزمون صحت در تمام فرمت‌ها

پس از تبدیل، مجموعه‌ای از بررسی‌های خودکار را اجرا کنید:

  1. مقایسهٔ چکسام – هش SHA‑256 منبع مارک‌داون را تولید کنید و همراه با فایل‌های خروجی ذخیره کنید. این ثابت می‌کند منبع بین ساخت‌ها تغییر نکرده است.
  2. اعتبارسنجی پیوندها – از pandoc --filter pandoc-citeproc استفاده کنید تا اطمینان حاصل شود هر ارجاع داخلی حل می‌شود.
  3. آزمون رستر‌سازی تصویر – PDF و EPUB را در نمایشگرهای جداگانه باز کنید و تأیید کنید تصاویر بیش از DPI موردنظر (معمولاً 300 dpi برای چاپ، 72 dpi برای صفحه‌نمایش) کاهش نیافته‌اند.
  4. ممیزی دسترس‌پذیری – ابزارهایی مثل pdfaPilot برای PDF یا axe-core برای HTML می‌توانند متن‌گزین缺失 یا ترتیب نادرست عناوین را شناسایی کنند.
  5. بررسی املایی – aspell یا hunspell را روی HTML یا PDF استخراج‌شده (از طریق pdftotext) اجرا کنید تا خطاهای انتقالی ناشی از فیلترها را بگیرید.

ادغام این چک‌ها در یک مسیر CI (GitHub Actions، GitLab CI) تضمین می‌کند هر تعهد یک مجموعهٔ اثبات‌شده از دارایی‌های قابل انتشار تولید کند.

خلاصهٔ جریان کاری

  1. منابع مارک‌داون و دارایی‌ها را جمع کنید. اگر Front‑matter ندارند، اضافه کنید.
  2. موتور تبدیل را انتخاب کنید (Pandoc برای کنترل کامل توصیه می‌شود).
  3. قالب‌ها و CSS را برای هر فرمت هدف پیکربندی کنید.
  4. دستورات تبدیل را اجرا کنید – PDF از طریق LaTeX، HTML با یک stylesheet کمینه، EPUB با متادیتا.
  5. خروجی‌ها را اعتبارسنجی کنید – چکسام، صحت پیوندها، دسترس‌پذیری و بازبینی بصری.
  6. با Makefile یا CI خودکار کنید تا فرآیند تکرارپذیر بماند.

با پیروی از این دستورالعمل می‌توانید اسناد پایدار و آماده انتشار را از یک منبع مارک‌داون واحد تولید کنید، چه برای راهنمای توسعه‌دهنده، کتابچهٔ دانشگاهی یا کتاب الکترونیکی برای توزیع.

تکنیک‌های شرح داده‌شده با سرویس‌های متمرکز بر حریم‌خصوصی مانند convertise.app سازگارند؛ این سرویس می‌تواند به‌عنوان نقطهٔ تبدیل بر‑تقاضا در صورت عدم دسترسی به ابزارهای محلی استفاده شود.