أدى انتقال Astro 7 إلى محرك markdown Sätteri القائم على Rust إلى تحويل عملية ترقية سلسة إلى كابوس ثلاثي الأبعاد للمواقع التي تعتمد على الرياضيات، ومرتكزات العناوين (heading anchors)، والتكوينات المخصصة. لا تزال المعادلات المضمنة (inline equations) تعمل، ولكن تظهر كتل الرياضيات المعروضة (display-math blocks) كقصاصات برمجية نصية عادية، وتختفي معرفات العناوين (heading IDs)، كما يتم تجاهل أي خيارات إضافية تضعها في تكوين Astro بصمت. يتعين على المطورين الذين ينتقلون من إصدارات Astro السابقة الآن إعادة كتابة الإضافات (plugins) أو المخاطرة بظهور صفحات معطلة.

لماذا يهم هذا التغيير

يقوم المحرك الجديد بتشغيل مبرز صياغة (syntax highlighter) مدمج قبل أي إضافات يقدمها المستخدم، ولا يقبل سوى ثلاثة حقول تكوين رئيسية. تتعارض هذه الخيارات مع الطريقة التي تضيف بها معظم مشاريع Astro الميزات: من خلال إضافات remark (MDAST) و rehype (HAST) التي يُتوقع تشغيلها بعد عملية التمييز (highlighting)، ومن خلال كائن تكوين مرن يتم تمريره إلى محلل markdown الأساسي.

تظهر التداعيات في أي صفحة تمزج بين رياضيات بأسلوب LaTeX والمحتوى العادي. تظهر الرياضيات المضمنة ($a+b$) بشكل جيد، ولكن كتلة العرض ($$a+b$$) يتم تغليفها في وسم <pre>، مما يعرض علامات التنسيق الخام بدلاً من معادلة منسقة. تختفي مرتكزات العناوين (heading anchors) التي تشغل روابط جدول المحتويات أو الروابط العميقة (deep-linking) لأن إضافة توليد المعرفات (ID-generation plugin) تعمل قبل معالج المعرفات المدمج، مما لا يترك شيئًا لإضافة الروابط التلقائية (autolink plugin) للارتباط به. المطورون الذين حاولوا ضبط مبرز صياغة Shiki باستخدام كائن shikiConfig وجدوا أن الإعداد قد اختفى دون أثر.

الإصلاحات التقنية

1. عرض الرياضيات قبل التمييز (highlighting)

السبب الجذري هو ترتيب العمليات: يقوم مبرز Sätteri بالاستحواذ على النص أولاً، ويصنف كتلة الرياضيات ككود عادي. لاستعادة الرياضيات، انقل المعالجة إلى طبقة MDAST (شجرة الصياغة المجردة التي تمثل markdown قبل تحويله إلى HTML). استبدل أي إضافات رياضيات على مستوى HAST بما يعادلها في MDAST وقم بتشغيلها قبل خطوة التمييز. من الناحية العملية، استبدل إضافات remark-math بإصدار يتصل بمرحلة تحليل markdown، ثم اترك المبرز يعمل على عقد الرياضيات التي تم تحويلها بالفعل.

2. إعادة ترتيب إضافات معرفات العناوين (heading-ID plugins)

يتم إنشاء معرفات العناوين بواسطة إضافة مدمجة يتم تنفيذها الآن بعد إضافات المستخدم. انقل مولدات المعرفات (ID) أو الروابط اللطيفة (slug) المخصصة إلى رأس قائمة الإضافات لتعمل أولاً. يبدو التسلسل النموذجي الذي يستعيد روابط المرتكزات كما يلي:

  1. إضافة slug/ID
  2. إضافة autolink
  3. أي إضافات remark أخرى

مع وجود المعرفات في مكانها مبكراً، يمكن لإضافة autolink إرفاق عناصر <a> المتوقعة، وسيشير جدول المحتويات إلى الأقسام الصحيحة.

3. الالتزام بمخطط التكوين الصارم لـ Sätteri

لا يعترف Sätteri إلا بثلاثة حقول في تكوين Astro markdown. أي شيء آخر، مثل shikiConfig يتم تجاهله بصمت. للحفاظ على السمات المخصصة أو تعديلات المبرز، انقل تلك الإعدادات إلى المستوى المناسب في تسلسل تكوين Astro الهرمي.

دليل الاستبدال السريع

إذا كنت تقوم بنقل حزمة Astro markdown كلاسيكية، فاستبدل إضافات remark القديمة بعلامات الميزات (feature flags) الجديدة التي يفهمها Sätteri:

  • remark-gfm → features.gfm
  • remark-frontmatter → features.frontmatter
  • remark-math → features.math
  • remark-directive → features.directive
  • remark-smartypants → features.smartPunctuation
  • remark-wiki-link → features.wikilinks

تتيح هذه العلامات نفس الإمكانيات دون الحاجة إلى تحميل إضافة منفصلة.

قواعد لإبقاء الإضافات متوافقة مع Sätteri

  • تمريرة واحدة فقط (Single pass only) – ترى الإضافات الشجرة مرة واحدة فقط؛ ولا يمكنها إعادة زيارة العقد التي يتم إنشاؤها لاحقاً في خط الإنتاج.
  • مصنع للحالة (Factory for state) – قم ببناء كائن حالة جديد لكل صفحة لتجنب تسرب البيانات بين الصفحات.
  • عقد غير قابلة للتغيير (Immutable nodes) – قم بإرجاع عقدة جديدة عندما تحتاج إلى إجراء تغيير؛ فمن شأن تعديل عقدة موجودة أن يؤدي إلى كسر خطوات المعالجة اللاحقة.
  • لا توجد أجزاء جذرية (No root fragments) – قم بإدراج العناصر المتجاورة (siblings) من خلال مساعدي الإدراج المقدمين بدلاً من إنشاء عقدة جزء (fragment node) في المستوى الأعلى.

عندما تقوم بتكييف إضافة موجودة، لا تعتمد على مخرجات المثال الموجود في ملف README. قم بتصيير (render) الـ HTML الخاص بالإضافة الأصلية، والتقط تلك العلامات، واستخدمها كنقطة مرجعية لإصدارك المتوافق مع Sätteri.

الخلاصة

يوفر محرك Sätteri الخاص بـ Astro 7 السرعة، ولكنه يفرض إعادة ترتيب لسلسلة معالجة Markdown: قم بعرض المعادلات الرياضية على مستوى MDAST، وضع إضافات heading-ID في المقدمة، واقتصر الإعدادات على الحقول الثلاثة المقبولة. اتبع مخطط feature-flag mapping، والتزم بقواعد single-pass و immutable-node، وستتمكن من استعادة المعادلات الرياضية، والروابط (anchors)، والتنسيقات المخصصة (custom theming) التي يعتمد عليها موقعك. الجهد المطلوب يكون في البداية؛ لكن النتيجة هي مسار معالجة Markdown أسرع وأكثر قابلية للتنبؤ.