ما تستلمه من Markdown، وكيف تنظّفه
آخر مراجعة
يعطيك التحويل ملف Markdown لا مستنداً منجزاً. وهذا دليل ميداني قصير لما يخرج، ولأي الأجزاء يمكن الوثوق بها، وللعدد القليل من التعديلات التي تستحق العناء قبل أن يدخل الملف مستودعاً أو ويكي أو خزانة ملاحظات.
قراءة في 7 دقائق
ما هو المُخرَج فعلاً
يُخرج المحوّل GitHub Flavored Markdown، وهي اللهجة التي يستعملها GitHub وGitLab وObsidian واستيراد Notion ومعظم مولّدات المواقع الساكنة. وهي CommonMark مع إضافات قليلة، أهمها هنا جداول الأنابيب.
وهذا اختيار مقصود. فـCommonMark الصِرف لا صياغة جداول فيه إطلاقاً، ومن ثم فالمحوّل الذي يستهدفه إما أن يُسقط الجداول وإما أن يُخرج HTML خاماً. أما جداول GFM فتُقرأ نصاً وتُفهم في كل مكان تقريباً يُفهم فيه Markdown.
ما ينجو من الرحلة
| العناوين | نعم — بصيغة #، ##، ### من الحجم النسبي للخط |
|---|---|
| الفقرات | نعم — من التباعد الرأسي |
| العريض والمائل | نعم — من وزن الخط وميله الفعليين |
| القوائم النقطية | نعم — من رموز التنقيط في بداية السطر |
| القوائم المرقّمة | نعم — من الأرقام في بداية السطر |
| الجداول | المستطيلة البسيطة، بصيغة جداول أنابيب GFM |
| code داخل السطر | نعم — من المقاطع ثابتة العرض |
| الروابط | نعم، حيث يحمل PDF تعليق رابط حقيقياً |
| الصور | لا — المُخرَج نص وبنية فقط |
| الحواشي | نصاً في آخر الصفحة، دون ربط |
| الرياضيات | بالحروف التي تتألف منها، لا بصيغة LaTeX |
| اللون والخطوط | لا — لا وسيلة في Markdown للتعبير عنهما |
التعديلات الخمسة التي تستحق التكرار
تحتاج معظم الملفات المحوَّلة إلى المجموعة القليلة نفسها من الجولات. تستغرق دقيقتين وهي الفارق بين ملف يمكن البحث فيه وملف يمكن قراءته.
- أصلح سُلَّم العناوين. تنتج عتبات الحجم مستوياتٍ صحيحةً محلياً ومتفاوتةً إجمالاً — قد ينتهي المستند بثلاثة عناوين H1 وبلا H2 واحد. تصفّح العناوين وحدها وأعد ترقيمها ليطابق التعشيش المخطط الحقيقي للمستند.
- أعد وصل الفقرات المشطورة. المستند سخي التباعد يكسر الفقرات عند نهايات الأسطر، فتُقرأ كومةَ أسطر قصيرة؛ صِلها واحذف الأسطر الفارغة الزائدة.
- أصلح فصل الكلمات بالشرطة. النص المضبوط بالشرطات عند الهامش يترك كلمات مشطورة بين سطرين. ابحث في الملف عن شرطة يليها فاصل سطر مباشرة.
- افحص كل جدول. عُدّ الأعمدة في Markdown بمقابلة الأصل، وافحص الصف الأخير — فالصف الختامي هو الضحية الأشيع. والجدول الذي فقد شكله تعاد كتابته عادةً أسرع مما يُصلَح.
- احذف أثاث الصفحة. تُكتشف الترويسات والتذييلات المتكررة وتُزال، لكن المستند الذي يغيّرها — عنوان فصل مختلف في كل صفحة — قد يخلّف بقايا.
ملاحظة عن الجداول
يحتاج جدول الأنابيب في GFM إلى العدد نفسه من الخلايا في كل صف، وصفُّ الفصل تحت الترويسة هو ما يحدد عدد الأعمدة للجدول كله. فإن أخطأ المحوّل عدّ صف واحد صار الجدول غير صالح وظهر نصاً حرفياً فيه أنابيب.
وهذا إخفاق مرئي، وتلك نعمة: ستراه فوراً بدل أن تكتشفه لاحقاً. الجدول الآتي مكسور:
| Region | Q1 | Q2 |
| --- | --- | --- |
| North | 120 | 140 |
| South | 95 |
| East | 88 | 102 |كيف يُصلَح
أضف الخلية الناقصة، فارغةً إن كانت خلية المصدر فارغة. وعلى كل صف أن يحمل من الأنابيب مثل ما يحمله صف الفصل.
| Region | Q1 | Q2 |
| --- | --- | --- |
| North | 120 | 140 |
| South | 95 | |
| East | 88 | 102 |الهروب، ولماذا يظهر في المُخرَج أحياناً شرطة مائلة عكسية
يمنح Markdown معنىً لحروف ترد في النثر العادي. فالنجمة تعني التوكيد، والشرطة السفلية تعني التوكيد، وعلامة المربع في أول السطر تعني عنواناً، والرقم المتبوع بنقطة في أول السطر يعني عنصر قائمة.
وحين ترد هذه الحروف في مستندك بوصفها نفسها — علامة حاشية، أو اسم متغير فيه شرطات سفلية، أو سطر يبدأ فعلاً بـ«1985.» — وجب الهروب منها بشرطة مائلة عكسية وإلا غيّرت في صمت طريقة عرض المستند. والشرطة المائلة العكسية في المُخرَج هي في الغالب احتياط من المحوّل لا خطأ منه.
وإن كانت إحداها معترضة طريقك فحذفها آمن، ما دمت تتحقق بعده من شكل السطر.
إلى أين يذهب الملف بعد ذلك
Markdown نص صِرف، وهذا هو سبب التحويل ابتداءً: يمكن البحث فيه بـgrep، ومقارنته بـdiff، وقراءته بعد خمسين عاماً بأي شيء يفتح ملفاً نصياً.
للمستودع، ضعه في الشجرة ودع مراجعة الشيفرة تؤدي عملها. ولخزانة الملاحظات، افحص سُلَّم العناوين أولاً، فمعظم الخزائن تبني مخططها منه. وللموقع الساكن، أضف front matter الذي يحتاجه مولّدك — لا يستطيع أي محوّل اختراعه لأنه ليس في PDF. ولتغذية نموذج لغوي، انظر دليل تهيئة ملفات PDF للاسترجاع؛ فذاك عمل آخر بأولويات أخرى.