تحويل Markdown إلى صيغ جاهزة للنشر

أصبح Markdown اللغة المشتركة للمطورين والكتاب ومجتمعات المصدر المفتوح. صيغته النصية السهلة تجعلها قابلة للكتابة والتحكم في الإصدارات والعرض عبر المنصات. ومع ذلك، لا يزال معظم الجمهور يتوقع ملفات PDF مصقولة، صفحات HTML متجاوبة، أو كتب إلكترونية بصيغة EPUB. تحويل Markdown إلى هذه الصيغ النهائية دون فقد العناوين أو الجداول أو كتل الشيفرة أو البيانات الوصفية قد يكون أصعب مما يبدو. الدليل التالي يستعرض سير عمل قابل للتكرار يوازن بين الدقة والأداء والخصوصية.

فهم المادة المصدرية

قبل أي تحويل، عُدِّ ملف الـ Markdown كـ وثيقة مصدر وليس كمنتج نهائي. حدِّد العناصر التي تحتاج إلى معالجة خاصة:

• بيانات التعريف (front‑matter) (العنوان، المؤلف، التاريخ، الوسوم). في كثير من مولدات المواقع الثابتة تظهر كـ YAML محاط بـ ---. احفظها لأن الصيغ النهائية غالبًا ما تحتاجها لصفحات الغلاف أو للبيانات الوصفية المدمجة.
• أسوار الشيفرة مع معرفات اللغة. يجب أن يبقى تمييز الصياغة (syntax highlighting) بعد التحويل، خاصة للكتب التقنية.
• الجداول، الحواشي، وقوائم التعريف. لا تدعم جميع الصيغ المستهدفة هذه العناصر بشكل أصلي؛ قد تحتاج إلى تحويلها إلى <table> في HTML أو هياكل جداول PDF.
• الصور والملفات المشار إليها بمسارات نسبية. يجب على خط أنابيب التحويل حل هذه المسارات وربما تضمين البيانات الثنائية.
• الروابط الداخلية (مثلًا [Section](#section)) والمراجع عبر المستندات. عند توليد ملف PDF أو EPUB واحد، يجب أن تتحول إلى إشارات مرجعية أو روابط تشعبية فعّالة.

بتصنيف هذه الجوانب مبكرًا، تتجنب المفاجآت لاحقًا في سير العمل.

اختيار محرك التحويل المناسب

هناك ثلاث عائلات رئيسية من المحولات للـ Markdown:

1. أنابيب مبنية على Pandoc – Pandoc هو محول وثائق عالمي يمكنه قراءة Markdown وإنتاج PDF، HTML، EPUB، DOCX، والعديد من الصيغ الأخرى. يتفوّق في معالجة الاقتباسات، الحواشي، والقوالب المخصَّصة.
2. مولدات المواقع الثابتة (SSGs) – أدوات مثل Hugo أو Jekyll أو MkDocs تحول Markdown إلى HTML باستخدام أنظمة القوالب. هي مثالية عندما تحتاج إلى موقع ويب كامل ولكن يمكن دمجها أيضًا مع أدوات الطباعة بدون رأس.
3. الخدمات القائمة على الويب – منصات مثل convertise.app تُعرِض نقطة نهاية REST تستقبل ملف Markdown وتُعيد الصيغة المختارة. تكون مفيدة للتحويلات الفردية دون الحاجة لتثبيت برامج.

لتحقيق سير عمل قابل للتكرار مع أولوية الخصوصية، يُفضَّل تثبيت Pandoc محليًا. فهو يعمل بالكامل على جهاز المستخدم دون ترك أي أثر على خادم بعيد.

تحضير البيئة

1. ثبت Pandoc (أحدث نسخة مستقرة) وتوزيعة LaTeX (مثل TinyTeX) إذا كنت تنوي توليد PDFs.
2. أنشئ بيئة افتراضية (Python venv أو Node nvm) لعزل الأدوات المساعدة.
3. اجمع الأصول – انسخ جميع الصور وملفات PDF وخطوط الكتابة إلى مجلد واحد. سيجعل ذلك حل المسارات بسيطًا للمحول.
4. أنشئ ملف بيانات تعريف – إذا كان ملف الـ Markdown يفتقر إلى front‑matter، اكتب ملفًا صغيرًا 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

يستخدم Pandoc LaTeX في الخلفية لإنتاج PDF. القالب المصمم جيدًا يتحكم في الهوامش، أنماط الرأس/التذييل، الخطوط، وعرض كتل الشيفرة. قالب 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 وتأكد من:

• ظهور جميع العناوين في جدول المحتويات مع أرقام الصفحات الصحيحة.
• وضوح كتل الشيفرة مع الحفاظ على ألوان اللغة.
• تضمين الصور (ليس ربطها) وتناسبها النسبي.
• ظهور البيانات الوصفية (المؤلف، العنوان) في خصائص المستند (ملف → خصائص → وصف).

إذا لاحظت نقصًا في أي عنصر، عدّل القالب أو أضف فلاتر Pandoc (مثل pandoc-citeproc للاقتباسات).

التحويل إلى HTML

HTML هو الناتج الأصلي لمعظم محركات Markdown، لكن للحصول على مخرجات جاهزة للنشر تحتاج إلى شفرة نظيفة دون الفئات الإضافية التي تضيفها SSGs.

الخطوة 1: اختيار إطار CSS بسيط

ورقة أنماط خفيفة مثل 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: تحسين إمكانية الوصول

• أضف lang="ar" إلى وسمة <html> (Pandoc يفعل ذلك تلقائيًا إذا عيّنت lang=ar).
• تأكّد من أن جميع الصور تحمل سمة alt؛ إذا كانت Markdown تفتقدها، أضفها عبر فلتر Pandoc أو بتحرير المصدر.
• تحقق من تسلسل مستويات العناوين بطريقة هرمية (h1 → h2 → h3).

الخطوة 4: الاختبار في المتصفحات

افتح output.html في Chrome وFirefox وEdge. تأكّد من أن كتل الشيفرة قابلة للتمرير على شاشات ضيقة وأن جدول المحتويات يتقلص بسلاسة. استخدم Lighthouse (المدمج في Chrome DevTools) لتتأكد أن الصفحة تحصل على نقاط جيدة من حيث الأداء وإمكانية الوصول.

التحويل إلى EPUB (كتاب إلكتروني)

EPUB هو في أساسه أرشيف ZIP يحتوي على XHTML، CSS، وبيانات وصفية. Pandoc يُبسط العملية وينتج حزمة مرتّبة.

الخطوة 1: تحسين بيانات وصفية EPUB

استخدم خيار Pandoc --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>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: تشغيل 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.

التعامل مع تضمين الأصول وحل المسارات

غالبًا ما يشير Markdown إلى صور بمسارات نسبية (![](images/logo.png)). أثناء التحويل قد تحتاج إلى تضمين هذه الأصول بدلاً من ترك روابط خارجية، خصوصًا للـ PDF وEPUB.

• يمتلك Pandoc خيار --resource-path لتحديد المواقع التي يبحث فيها عن الأصول.
• علم --extract-media=./media ينسخ أي وسائط مرتبطة إلى مجلد media ويعيد كتابة الوسوم لتشير إلى النسخ.
• للـ 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

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

pdf
---

تُعيد الاستجابة ملف PDF محوَّلًا كتيار ثنائي. يناسب هذا النهج المهام الفردية، لكن بالنسبة لسلاسل النشر القابلة للتكرار يظل حل Pandoc المحلي هو الأكثر شفافية وقابلية للمراجعة.

اختبار الدقة عبر الصيغ

بعد التحويل، شغِّل مجموعة من الفحوصات الآلية:

1. مقارنة التجزئة – احسب تجزئة SHA‑256 لملف Markdown المصدر واحفظها جنبًا إلى جنب مع ملفات الناتج. يثبت ذلك أن المصدر لم يتغيّر بين البنيات.
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. اجمع ملفات Markdown المصدرية والأصول. أضف front‑matter إذا كان مفقودًا.
2. اختر محرك التحويل (Pandoc هو الموصى به للسيطرة الكاملة).
3. إعداد القوالب وCSS لكل صيغة هدف.
4. شغّل أوامر التحويل – PDF عبر LaTeX، HTML مع ورقة أنماط بسيطة، EPUB مع بيانات وصفية.
5. تحقق من المخرجات – التجزئة، سلامة الروابط، إمكانية الوصول، والفحص البصري.
6. أتمتة باستخدام Makefile أو CI للحفاظ على تكرار العملية.

اتباع هذه الوصفة ينتج وثائق جاهزة للنشر من مصدر Markdown واحد، سواء كنت تُعد دليل مطورين، كتيّب أكاديمي، أو كتابًا إلكترونيًا للتوزيع.

---

التقنيات الموضحة هنا متوافقة مع الخدمات التي تركّز على الخصوصية مثل convertise.app، التي يمكن أن تكون نقطة تحويل اختيارية عند عدم توفر الأدوات المحلية.