طريقة الاستخدام
- اكتب النص أو الصقه في Markdown. تظهر شيفرة HTML تحته أثناء الكتابة.
- اقرأ المعاينة لترى شكل الصفحة. تُعرض الجداول وقوائم المهام وكتل الشيفرة كما يعرضها GitHub.
- انسخ شيفرة HTML والصقها في صفحتك، أو استخدم تنزيل لحفظ مستند كامل باسم markdown.html.
ما الذي يدعمه التحويل
يتبع المحوّل مواصفة GitHub Flavored Markdown: العناوين، والتأكيد والنص العريض، والقوائم، واقتباسات الكتل، وشيفرة السطر، وكتل الشيفرة المسيّجة مع اسم اللغة، والروابط والصور، والجداول مع محاذاة الأعمدة، والشطب بشرطتين مائلتين عكسيتين، وقوائم المهام بمربعات الاختيار، وعناوين الويب التي تتحول إلى روابط. ويحافظ سطر الانتهاء الواحد داخل الفقرة على كونه فاصل سطر في المصدر، لا في HTML؛ ولبدء فقرة جديدة اترك سطراً فارغاً.
يقرأ Markdown وHTML المحرك نفسه، لذلك يُنسخ HTML الخام المكتوب داخل النص إلى الخرج. ولا يُنظَّف الخرج، لأنه الشيفرة التي طلبتها. وتعمل المعاينة في إطار لا يشغّل نصوصاً برمجية ولا يرسل النماذج، فلا تعمل أي نصوص برمجية في النص داخل هذه الصفحة.
- استخدم كتلة شيفرة مسيّجة بثلاث علامات اقتباس عكسية مع اسم اللغة، مثل js، حتى تحتفظ الشيفرة بفواصل أسطرها.
- أبقِ النص أقل من 200,000 حرف؛ فالنص الأطول لا يُحوَّل في المتصفح.
نسخ النتيجة وتنزيلها
الشيفرة المعروضة هي جزء HTML الذي يكتبه المحوّل، دون الصفحة التي حوله. أما التنزيل فمستند HTML كامل بترميز UTF-8، فتظهر الحروف العربية وغيرها من الحروف غير اللاتينية بشكل صحيح عند فتح الملف في المتصفح. وعنوانه هو أول عنوان في النص.
مثال محلول: عنوان وقائمة وجدول
يبدأ نص العينة بعنوان من المستوى 1، فيصبح عنصر h1. وقائمته فيها بند واحد فيه رابط، وبندان للمهام؛ المهمة الأولى مُعلَّمة والثانية غير مُعلَّمة، فتعطي شيفرة HTML المربع الأول مُعلَّماً والثاني فارغاً.
للجدول صف عناوين، وصف لكل سطر من سطريه. والشطب في عموده الأول يصبح عنصر del، وهو ما تعرضه المتصفحات بخط يمر عبر النص.
الأسئلة الشائعة
أي نكهة من Markdown يستخدم هذا المحوّل؟
يستخدم GitHub Flavored Markdown، وهي النكهة المستخدمة في GitHub لملفات README والتعليقات، مع الجداول وقوائم المهام والشطب والروابط التلقائية. وبعض امتدادات الأدوات الأخرى، مثل الحواشي أو المعادلات، ليست جزءاً منها.
لماذا لا يبدأ سطر انتهاء واحد فقرة جديدة؟
في Markdown يكون سطران دون سطر فارغ بينهما في فقرة واحدة، فيعرضهما المتصفح كسطر واحد. والسطر الفارغ يبدأ فقرة جديدة. وهذه قاعدة المواصفة، فيطابق الخرج ما يعرضه GitHub.
هل شيفرة HTML آمنة لوضعها في موقعي؟
لا ينظّف المحوّل شيفرة HTML، فيُكتب كل نص برمجي أو خاصية غير آمنة تكتبها في النص إلى الخرج كما هي. فراجع الشيفرة، واحذف ما لا تثق به قبل نشرها.
لماذا رُفض نصي؟
النص أطول من 200,000 حرف. ومثل هذا النص الطويل يبطئ المتصفح، لذلك تحوّل الصفحة النصوص الأقصر فقط. حوّله على أجزاء، أو حوّله على حاسوبك باستخدام أداة سطر أوامر.
هل يُرسل Markdown الذي أكتبه إلى خادم؟
لا. يعمل التحويل في متصفحك، وتعمل المعاينة في إطار داخل الصفحة. ولا يُرسل ما تكتبه إلى خادمنا ولا يُخزَّن هناك.
المصادر
- GitHub Flavored Markdown Spec (باللغة الإنجليزية)
- marked (باللغة الإنجليزية): a Markdown parser and compiler
آخر مراجعة للأرقام والنص: الثلاثاء، 30 جمادى الأولى 1448 بعد الهجرة.