تحويل Markdown إلى HTML

مقتطف أم صفحة، وأيهما تحتاج

هناك مُخرَجان مفيدان، ولا يغني أحدهما عن الآخر. المقتطف هو الترميز المحوَّل فقط — العناوين والفقرات والقوائم والروابط — دون غلاف المستند، وهو ما تحتاجه حين تضع النتيجة في قالب أو حقل في نظام إدارة محتوى أو صفحة أخرى. أما الصفحة الكاملة فتضيف تعريف doctype وقسم head وتصريح ترميز الأحرف وورقة أنماط، فتُفتح وحدها ويكون لها مظهر لائق. لصق صفحة كاملة في نظام إدارة محتوى يعطيك مستندًا داخل مستند؛ ولصق مقتطف في المتصفح يعطيك نصًا بلا تنسيق.

يغطي التحويل مجموعة Markdown الموسّعة المتفق عليها على نطاق واسع: العناوين، والتأكيد، والقوائم، والروابط، والصور، والاقتباسات، والجداول، وكتل الكود مع تلوين الصياغة، وقوائم المهام، والنص المشطوب، والحواشي. وتحصل العناوين على معرّفات مشتقة من نصها، فيمكن الربط إليها مباشرة — وهي روابط الإرساء التي تجعل الوثائق الطويلة سهلة الاستخدام.

يُمرَّر HTML الخام داخل Markdown كما هو، وهذا جزء من المواصفة ويستحق أن تتعامل معه بوعي: فهو يعني أن ملف Markdown من مصدر غير موثوق قد يحتوي على وسم script، وأن تحويله ينتج صفحة تحمل ذلك السكربت. لا تعرض أبدًا Markdown من غرباء دون تعقيم HTML بعد ذلك — فالتحويل ليس حاجزًا أمنيًا ولم يُصمَّم ليكون كذلك أصلًا.

يُخرَج شيئان ككتل كود بدلًا من عرضهما، وذلك عن قصد. المعادلات الرياضية بصيغة LaTeX تحتاج إلى مكتبة تنضيد، ومخططات Mermaid تحتاج إلى أداة لرسم المخططات — وكل منهما اعتمادية ضخمة، والمعادلة المعروضة بشكل خاطئ أسوأ من معادلة ظاهرة ككود. وتستخدم الصفحة الكاملة خطوط النظام العادية بدلًا من جلب أي خطوط، فتعمل دون اتصال ويختلف مظهرها قليلًا بين Windows وmacOS وLinux.

عندما تحتاج إلى شيء آخر

Pandoc يتولى الأجزاء التي تُركت هنا وأكثر بكثير: الأمر pandoc in.md -o out.html --mathjax --standalone --toc يعرض المعادلات بشكل صحيح، وينشئ جدول محتويات، ويقبل قالبًا لتطابق النتيجة موقعك. كما يحوّل من وإلى نحو أربعين صيغة أخرى، ولهذا يستحق أن تثبّته مرة واحدة.

لموقع ويب لا لملف، استخدم مولّد مواقع بدلًا من تحويل الصفحات واحدة تلو الأخرى. Hugo وEleventy وJekyll وMkDocs تحوّل مجلدًا من ملفات Markdown إلى موقع بتنقل وبحث وتنسيق موحّد، وتعيد بناءه كلما تغيّر المصدر — وهذه هي المهمة الفعلية متى كان لديك أكثر من مستند واحد.