تم تحويل MDN إلى Markdown

2022-04-19 - ويل بامبرج

في عام 2021 ، قام فريق Open Web Docs ، بمساعدة Mozilla و W3C ومجتمع توثيق الويب الأوسع ، بتحويل تنسيق تأليف مستندات الويب MDN - جميع الصفحات البالغ عددها 11000 - من HTML إلى Markdown. سنشرح في هذه المقالة سبب قيامنا بذلك ، وكيف فعلناه وكيف حدث. حساء HTML

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

في عام 2020 ، استبدلت MDN Wiki القديم بمنصة جديدة حيث تم تخزين مصدر المستندات في مستودع GitHub كمجموعة من ملفات HTML ، وتم دمج ذلك في صفحات الويب بواسطة رمز Yari. كان لهذا العديد من المزايا الرئيسية ، لكنه كان يعني أن محرر WYSIWYG القديم لم يعد موجودًا. بدلاً من ذلك ، كان على جميع المؤلفين تحرير صفحات MDN كمستندات HTML أولية.

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

الاسم

غودزيلا

مولود

1952

مكان الميلاد

اليابان

اللون

أخضر

من الناحية العملية ، يجبر هذا الكتاب على التركيز كثيرًا على الترميز بحيث يصعب التركيز على الكتابة نفسها.

بالإضافة إلى ذلك ، واجه المؤلفون نتيجة 15 عامًا من قيام الأشخاص بلصق محتوى ثري في محرر WYSIWYG ، مما أدى إلى مصدر مثل هذا: عنصر const = driver.findElement (By.id ('myElementId')) ؛

كان من الواضح أنه من أجل صحة شبكة مطوري موزيلا على المدى الطويل ، كنا بحاجة إلى تجربة تأليف أفضل من هذه ، لكل من المساهمين المتطوعين والكتاب المتفرغين. اختر التنسيق ، الجزء 1 - Markdown

لم يكن استبدال HTML كتنسيق تأليف لـ MDN فكرة جديدة: لقد ناقشناها عدة مرات خلال السنوات القليلة الماضية. لقد أخذنا في الاعتبار كل من AsciiDoc و reStructuredText ، وبطرق عديدة ، تتفوق هذه التنسيقات على Markdown: فهي أكثر قوة ، وتدعم الترميز الدلالي ولديها قابلية توسعة مضمنة.

بدلاً من ذلك ، اخترنا Markdown لأن Markdown هو تنسيق واسع الاستخدام ومعتمد. يمنحنا هذا ميزتين رئيسيتين: تقريبًا أي شخص يأتي إلى MDN سيفهم Markdown جيدًا بما يكفي للمساهمة على الفور. على الرغم من أن العديد من مساهمات MDN تتطلب فهم التعقيد (الشديد في بعض الأحيان!) لـ MDN ، فإن العديد من المساهمات لا تفعل ذلك ، و Markdown يجعل هذه المساهمات بسيطة قدر الإمكان. هناك دعم أداة ممتاز ، وشفاف في كثير من الأحيان ، لـ Markdown. تحتوي معظم برامج تحرير الأكواد الحديثة على معاينة Markdown مضمنة. يدعم Prettier Markdown (وحتى عينات التعليمات البرمجية المضمنة في Markdown). يمكن لـ GitHub إظهار الاختلافات الغنية في Markdown. اختر تنسيقًا ، الجزء 2 - ولكن أي Markdown؟

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

كان من الممكن أن يسرع هذا المشروع ، لأن ...