طريقة الاستخدام
- الصق شيفرة HTML في HTML. تعرض العينة عنواناً وفقرة فيها تأكيد ورابطاً، وقائمة.
- اقرأ Markdown (CommonMark): يتحدث مع كتابتك.
- انسخه بزر النسخ واحفظه ملف .md، أو الصقه في محرر Markdown.
ما الذي يتحول وكيف
تصبح العناوين h1 إلى h6 عناوين ATX بعدد من علامات # من واحدة إلى ست. وتصبح strong وb نصاً عريضاً، وتصبح em وi نصاً *مائلاً*. ويصبح عنصر code شيفرة مضمّنة، ويصبح عنصر pre كتلة شيفرة محاطة بعلامات، مع الاحتفاظ باللغة إن وُجدت في صنف language-. ويصبح br سطر انتهاء صلباً، ويحصل blockquote على > قبل كل سطر، وتصبح ul وol قوائم بالرمز - أو برقم. ويصبح عنصر a الذي فيه href رابطاً، ويصبح img الذي فيه src صورة بنصها البديل (أقسام CommonMark 4.2 و4.5 و5.1 و5.2 و6.1 و6.2 و6.3 و6.7).
يُهرَّب كل رمز يقرؤه Markdown كأنه تنسيق، مثل النجمة والشرطة السفلية وعلامة الاقتباس العكسية والأقواس المربعة والقوس الزاوي، وكذلك كل سطر قد يبدو عنواناً أو اقتباساً أو قائمة. ويسمح القسم 2.4 من CommonMark بالشرطة المائلة العكسية قبل أي رمز ترقيمي من ASCII.
ما الذي لا يُحفظ
تُحذف النصوص البرمجية والأنماط والقوالب والإطارات وعناصر النماذج والوسائط مع محتواها. وتُحذف السمات غير href وsrc وalt وtitle. ولا تملك CommonMark جدولاً أو خطاً سفلياً أو لوناً، فيصبح الجدول فقرة لكل خلية، ويُحتفظ بنص u وspan وما شابهها دون تنسيقه.
ثلاثة عناصر ورمز واحد للتهريب
كل شيفرة HTML في الجدول تعطي Markdown في العمود الأيمن، كما تكتبه الأداة.
| ما تحتويه شيفرة HTML | Markdown |
|---|---|
| عنوان من المستوى 2 نصه ملاحظات | ## ملاحظات |
| فقرة فيها نص عريض | بعض **عريض** نص |
| قائمة فيها بند واحد هو الأول | - الأول |
| النص 5 * 3 = 15 مع نجمة | 5 * 3 = 15 |
الأسئلة الشائعة
لماذا تحتوي Markdown على شرطات مائلة عكسية؟
تدل الشرطة المائلة العكسية على أن الرمز التالي نص وليس تنسيقاً، مثل النجمة أو القوس المربع. ويزيلها CommonMark عند عرض Markdown (القسم 2.4)، فتعرض الصفحة الرموز كما كانت في HTML.
هل تشغّل الأداة HTML الذي أكتبه أم تحتفظ به في الصفحة؟
لا. يحلل DOMParser شيفرة HTML في مستند منفصل لا يملك سياق تصفح، ولا يشغّل نصوصاً برمجية. وتنسخ الأداة النص والبنية فقط، وتعرض Markdown كنص.
لماذا تتحول الجداول إلى فقرات؟
ليس في CommonMark صيغة للجداول، فجداول الأنابيب التي تضيفها بعض الخدمات امتداد لها. تصبح كل خلية فقرة، فتبقى الكلمات، لكن تخطيط الجدول لا يبقى.
هل تُحفظ الروابط والصور؟
نعم. يصبح عنصر a الذي فيه href رابطاً، مع عنوانه إن وُجد، ويصبح عنصر img الذي فيه src صورة يُهرَّب نصها البديل. أما السمات الأخرى فلا تُحفظ.
ماذا يحدث للعناصر التي ليس لها شكل في Markdown؟
يبقى نصها وتُحذف تنسيقاتها. فمثلاً تحتفظ span وu وmark بالكلمات التي تحتويها، ويبدأ عنصر div أو section فقرة نصية جديدة.
المصادر
- CommonMark Spec, version 0.31.2 (باللغة الإنجليزية): sections 2.4, 4.1, 4.2, 4.4, 4.5, 5.1, 5.2, 6.1, 6.2, 6.3 and 6.7
- WHATWG HTML Standard (باللغة الإنجليزية): section 8.5.1, The DOMParser interface
- MDN (باللغة الإنجليزية): DOMParser
آخر مراجعة للأرقام والنص: الثلاثاء، 30 جمادى الأولى 1448 بعد الهجرة.