كيف تعمل : من Markdown إلى HTML

كل رمز HTML في نصكم يُفلَت، بلا استثناء: فالنص البرمجي المكتوب في Markdown عندكم يخرج ظاهرا، لا قابلا للتنفيذ أبدا. وهذا أشد من المواصفة، وهو السلوك الآمن الوحيد لأداة تردّ ملفا سيفتحه أحد.

فتح الأداة

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

وفي الأمان، توضيح مذهبي يستحق الدقة. فالمواصفة تجيز نص HTML الخام في مستند Markdown، وقد تحققنا في نصها من أنها لا تطلب في أي موضع من التنفيذات تطهير مخرجاتها: فتعليمة «مرّروا النتيجة على مطهِّر» تأتي من وثائق بعض المكتبات، لا من المعيار. لذلك لن ننسبها إلى المعيار.

واختيارنا أبسط وأشد: فكل رمز HTML في نصكم يُفلَت. والوسم المكتوب في Markdown عندكم يخرج ظاهرا في النتيجة، لا فاعلا أبدا. وعناوين الروابط الخطرة مرفوضة بالاسم، مع حفظ الرابط نصا بسيطا وإشارة على الشاشة، وفقا للتوصية العمومية بألا يُسمح إلا بالعناوين بـhttp وhttps في خاصية عنوان.

كيف تعمل

الصقوا نص Markdown عندكم. هو لا يغادر جهازكم.
ضعوا العلامة على «صفحة كاملة» إن أردتم ملف HTML مستقلا بدل قطعة تُدرَج.
انسخوا النتيجة أو نزّلوها. وإن كانت ثمة عناوين مرفوضة، سمّاها الجدول.

الصيغ المقبولة

المجموعة الجزئية المحوَّلة: العناوين بعلامات الشباك والعناوين المسطَّرة، والفقرات، والغامق، والمائل، والمشطوب، والشيفرة الحرفية، وكتل الشيفرة المؤطَّرة بلغتها، والقوائم النقطية والمرقَّمة، والاقتباسات المتداخلة، والخطوط الأفقية، والروابط والصور بعناوينها، وفاصل السطر الصلب بمسافتين في آخر السطر. أما الجداول والحواشي وقوائم التعريفات فلا تُحوَّل: فهي لا تنتمي إلى المواصفة الأساسية.

نص بصيغة Markdown

حتى 200000 رمز. والنتيجة تخرج بصيغة HTML، قطعة أو صفحة مستقلة.

الاطلاع على جدول التوافق

حدودها

مجموعة جزئية من المواصفة، مسرودة أعلاه

في المواصفة المرجعية أكثر من خمسمئة مثال مطابقة، وكثير منها يغطي حالات لا يكتبها أحد قط: قوائم متداخلة بأربعة مستويات مع تتمة، ومراجع روابط معرَّفة في موضع أبعد، وكيانات HTML الرقمية. وتنفيذ خمسمئة حالة والتحقق منها سيكون مشروعا قائما بذاته. ونحن نؤثر إعلان ما يعمل بدقة: فهو وعد أصغر، وهو محفوظ.

نص HTML المكتوب في Markdown عندكم يُفلَت، ولا يُنسخ أبدا

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

لا يُحفَظ إلا العناوين بـhttp وhttps وmailto والعناوين النسبية

رابط Markdown يمكن أن يحمل أي مخطط عنوان، بما فيها التي تنفّذ شيفرة عند النقر. وتوصيات OWASP العمومية عن النصوص البرمجية المحقونة في صفحة تقول بألا يُسمح إلا بـhttp وhttps في خاصية عنوان. والأداة تتبع هذه القاعدة، وتحفظ نص الرابط، وتشير إلى العنوان المرفوض في جدول: فنزعه في صمت سيترككم تظنون أن الرابط يعمل.

الجداول لا تُحوَّل

صياغة الجداول بالشُّرَط الرأسية امتداد واسع الانتشار، لكنها لا تنتمي إلى المواصفة الأساسية: فكل تنفيذ يعاملها معاملة مختلفة قليلا، وبخاصة في المحاذاة والخانات الفارغة. ونحن لا ننفّذها بدل أن نردّ جدولا يختلف عن الذي تنتجه منصتكم المعتادة.

أسئلة عن هذه الأداة

هل يُرسَل نصي إلى مكان ما؟

لا. تحققوا في ثلاثين ثانية: افتحوا أداة الفحص بمفتاح F12، وتبويب «الشبكة»، وأفرغوا القائمة، ثم الصقوا نص Markdown وحوّلوه. لن يظهر أي سطر. واقطعوا اتصالكم وأعيدوا الكرّة: فالمحلّل مكتوب في الصفحة.

لماذا يظهر وسم HTML عندي بوضوح في النتيجة؟

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

أحد روابطي لم يعد قابلا للنقر.

لأن عنوانه يستعمل مخططا يتيح تنفيذ شيفرة عند النقر. والأداة تحفظ نص الرابط، وتنزع العنوان، وتسمّيه في جدول. فإن كان هذا الرابط آتيا من مستند لم تكتبوه بأنفسكم، فتلك معلومة تُؤخذ على محمل الجد. والعناوين المحفوظة هي التي بـhttp وhttps وmailto، والمراسي، والعناوين النسبية.

جداولي لا تُحوَّل.

لا، وذلك مكتوب في الحدود. فصياغة الجداول بالشُّرَط الرأسية امتداد واسع الانتشار لكنه غائب عن المواصفة الأساسية، وكل تنفيذ يعامله معاملة مختلفة في المحاذاة والخانات الفارغة. وردّ جدول لا يشبه جدول منصتكم المعتادة أسوأ من الإعلان صراحة بأننا لا نفعل ذلك.

هل النتيجة مطابقة للمواصفة؟

في المجموعة الجزئية التي نعلنها، هي تتبع قواعدها، بما فيها التي كثيرا ما تُنسى: فاصل السطر الصلب بمسافتين في آخر السطر، والشيفرة الحرفية التي تحمي محتواها من أي تأويل آخر، والاقتباسات التي تتداخل. أما ما عدا ذلك فلا ندّعي فيه شيئا: ففي المواصفة أكثر من خمسمئة مثال مطابقة، ولم نمارسها كلها. ولهذا كُتبت قائمة ما يعمل في أعلى الصفحة بدل شعار مطابقة.

الورشةمن Markdown إلى HTML

التحققالبرهان، خطوة خطوة

التحقق بفاحص الشبكة، مشروحا حركة حركة، مع لقطات الشاشة.

الركنركن النصوص والبيانات

العدّ، والمقارنة، والتنسيق، والتنظيف. تلك الحركات الصغيرة التي تُضيّع ساعة حين لا تكون في المتناول.