من Markdown إلى PDF والعكس: ما تحفظه عملية التحويل
يُبقي التحويل بين Markdown وPDF العناوين والقوائم والجداول البسيطة، لكن الخطوط الدقيقة وتقسيم الصفحات لا تنجو كدورة بلا خسارة.
يُحسّن Markdown وPDF عقدين مختلفين: Markdown بنية صديقة لنظام إدارة الإصدارات، وPDF وصف صفحة ثابت. والتحويل في اتجاه ثم العودة مفيد، لكنه ليس دورة أرشفة بلا خسارة.
من Markdown إلى PDF: البنية تصير صفحات
يقبل Markdown إلى PDF (POST /api/v1/convert/markdown/pdf) ملف .md أو ملف ZIP يحوي Markdown؛ ويُرفض كل رفع ليس Markdown وليس ZIP. ويُشترط UTF-8 للمدخل .md العادي. ويصيّر مسار Markdown إلى HTML مع تفعيل الجداول والشطب وقوائم المهام، ثم يلفّ ذلك HTML في CSS موجّه للطباعة، بما في ذلك مجموعات خطوط متعددة الكتابات ودعم RTL عند اكتشاف العربية، ثم يطبع إلى PDF عبر WeasyPrint.
وما ينجو عادةً من التمريرة الأمامية:
- العناوين والفقرات والقوائم والجداول البسيطة بصيغة Markdown
- نص متعدد الكتابات يستطيع مسار HTML تنسيقه (CJK واللاتينية وكتابات أخرى تغطيها CSS الطباعة)
- ملف PDF قابل للطباعة والمشاركة لسير عمل التوثيق كشيفرة
وما لا ينجو:
- خطوط سمة محرّرك كتطابق مضمون في كل عارض
- فواصل الأسطر الدقيقة كما في ملف
.mdعلى الشاشة - ميزات Markdown التفاعلية التي لا مقابل لها في PDF، مثل مربعات الاختيار الحيّة والأقسام القابلة للطي وروابط الويكي
ومدخل ZIP لتجميع Markdown مع أصول يستطيع مسار HTML إيجادها بجوار المستند. تعامل معه كتسهيل تعبئة، لا كضمان أن كل صورة نسبية أو مرجع CSS سيبدوان نفسيهما في كل عارض.
من PDF إلى Markdown: طبقة النص تدخل، وMarkdown يخرج
يستخرج PDF إلى Markdown (POST /api/v1/convert/pdf/markdown) المحتوى النصي إلى Markdown عبر pdf-inspector. والرد text/markdown يُنزَّل كملف .md. وتتحوّل أفضل ما يمكن الملفات الرقمية الأصلية ذات الطبقة النصية النظيفة، أما الصفحات الممسوحة بلا طبقة نصية فتُنتج Markdown فارغاً أو عديم الفائدة حتى تشغّل OCR أولاً، وOCR هنا يعيد Markdown أيضاً لا طبقة PDF قابلة للبحث.
وتوقّع:
- عناوين وفقرات حين تعمل استدلالات حجم الخط بشكل صحيح، وقد تحتاج مع ذلك إلى إعادة ترقيم مستويات
#يدوياً - جداول بصيغة Markdown حين تنجح المطابقة، وقد تتسطّح التخطيطات متعددة الأعمدة إلى ترتيب قراءة مختلف
- ترويسات وتذييلات متكررة في كل صفحة، فاقتطعها في المراجعة
- صوراً ومعادلات كصور لا تصبح تلقائياً أصولاً محلية ولا LaTeX
وإن احتجت نثراً مجرّداً بلا استدلالات عناوين، فـ PDF إلى نص هو الاستخراج الأكثر تسطيحاً. أما تصديرات الجداول التي تعيد HTTP 204 فتعني عدم اكتشاف أي كتل أعمدة؛ راجع تصدير جدول فارغ (204).
ما تثبته دورة الذهاب والعودة فعلاً
| ينجو بمعقولية | لا ينجو عادةً |
|---|---|
| الكلمات وتسلسل العناوين وبنية القوائم | هندسة الصفحة بدقة البكسل |
| الجداول البسيطة كنص | الخطوط الدقيقة والتقنين |
| مسودة صالحة لـ Git أو للوكلاء | تقسيم صفحات مطابق للطباعة |
وتمرير الدورة مرتين سيؤدي إلى انحراف. فـ Markdown إلى PDF يعيد التدفق عبر WeasyPrint، وPDF إلى Markdown يعيد بناء البنية من استدلالات الاستخراج. ولا خطوة منهما تخزّن وسيطاً بلا خسارة لنموذج تخطيط الصيغة الأخرى.
اختر اتجاهاً معيارياً
إن احتجت تخطيط الطباعة كنظام سجل، فاحفظ PDF واعتبر Markdown تصديراً أو تغذية للوكلاء. وإن احتجت الفروق ومراجعة الشيفرة وإدخال الوكلاء، فضّل Markdown واعتبر PDF خطوة النشر. ولا تخزّن الاثنين كأنهما «مصدرا حقيقة» متساويان وتتوقع أن يبقيا متطابقين بعد التحرير.
وحلقة توثيق-كشيفرة عملية: حرّر Markdown في Git، ثم Markdown إلى PDF للمنتج القابل للمشاركة، وتجنّب دورة PDF ثم Markdown ثم PDF كعادة يومية. استخدم PDF إلى Markdown حين ورثت ملفاً رقمياً أصلياً وتحتاج نصاً لوكيل، ثم عامل ذلك Markdown كمسودة جديدة لا كضمان لتقسيم الصفحات الأصلي.
وتحتاج الملفات المشفّرة فكّ قفل مصرّحاً به قبل أي من التحويلين. أما الملفات التالفة التي لا تُحلَّل فينبغي أن تمرّ بـ Get Info أو الإصلاح أولاً. ولمعرفة النقاط نفسها عبر HTTP، راجع المطوّرين.