Astro 7 Upgrade Breaks Math, Heading Links and Custom Options – How to Fix It

أدى انتقال Astro 7 إلى محرك Markdown المعتمد على Rust والمسمى Sätteri إلى تحويل كتل الرياضيات المعروضة (display-math) إلى مجرد أكواد برمجية عادية، وإزالة مرابط العناوين (heading anchors)، والتخلص من خيارات Markdown المخصصة – وهي نقطة ألم لأي شخص قام بالترقية ويواجه الآن معادلات معطلة على موقعه.

إذا كنت تعتمد على رياضيات بأسلوب LaTeX، أو روابط العناوين التلقائية، أو إضافات (plugins) Markdown مخصصة، فإن الترقية قد تجعل محتواك غير قابل للقراءة وتجعل التنقل في موقعك غير ممكن، لذا فإن إصلاح ذلك بسرعة أمر ضروري.

لماذا تسببت الترقية في تعطل الأمور

يعمل Astro الآن باستخدام Sätteri كمُعالج Markdown أساسي. يقوم Sätteri بتغيير الترتيب الذي يتم به تطبيق الإضافات: حيث يقوم بتشغيل تمييز الصيغة (syntax highlighting) قبل إضافات HTML-AST (HAST) التي قد تكون قمت بتكوينها. هذا التحول يعني توقف ثلاثة أنماط شائعة عن العمل:

• الرياضيات المعروضة (Display math) – تُعامل الكتل المحصورة بين $$ … $$ كأكواد عادية لأن مُميّز الصيغة يعمل أولاً.
• مرابط العناوين (Heading anchors) – الإضافات التي تُنشئ الروابط النصية (slugs) (معرفات متوافقة مع URL) ثم تقوم بربط تلك العناوين تلقائياً لم تعد ترى المعرفات (IDs)، وبالتالي لا يتم إنشاء الروابط أبداً.
• الخيارات المخصصة (Custom options) – يتم تجاهل أي إعدادات إضافية قمت بتمريرها مباشرة إلى مُعالج Sätteri؛ حيث يقوم Astro بتمرير ثلاثة حقول محددة مسبقاً فقط.

الإصلاحات الملموسة

1. قم برسم الرياضيات على markdown-AST (MDAST) بدلاً من HTML-AST

يحتوي مسار معالجة Markdown في Astro على مكانين للإضافات:

• mdastPlugins – تعمل على شجرة Markdown التي تم تحليلها قبل تحويلها إلى HTML.
• hastPlugins – تعمل على شجرة HTML بعد التحويل.

نظرًا لأن مُميّز الصيغة يعمل قبل hastPlugins ، يتم تحويل الرياضيات إلى كتلة كود. انقل إضافة الرياضيات الخاصة بك إلى mdastPlugins.

export default {
  markdown: {
    mdastPlugins: [
      // put remark-math (or your custom math handler) here
    ],
    // leave hastPlugins for things that truly need HTML nodes
  }
}

2. أعد ترتيب إضافات الـ slug والـ autolink للعناوين

تقوم الإعدادات القياسية بتثبيت مُنشئ slug تتبعه إضافة autolink. في Astro، تعمل إضافة heading-ID المدمجة بعد قائمتك، مما لا يترك شيئاً لإضافة autolink لترتبط به. ضع إضافة slug أولاً في القائمة، ثم إضافة autolink.

export default {
  markdown: {
    mdastPlugins: [
      satteriSlug(),            // must be first
      satteriAutolinkHeadings() // runs after slug, sees IDs
    ]
  }
}

الآن يتلقى كل عنوان معرفاً (ID) ويمكن لإضافة autolink تغليفه بالمرابط المناسب.

3. ضع التكوينات الإضافية في المستوى الأعلى لكائن Astro markdown

يقوم Astro بتمرير ثلاثة حقول محددة فقط إلى مُعالج Sätteri. أي شيء تضعه داخل المُعالج (على سبيل المثال كائن shikiConfig) سيتم تجاهله. انقل تلك الإعدادات الإضافية إلى المستوى الأعلى من تكوين markdown.

export default {
  markdown: {
    shikiConfig: { theme: 'nord' }, // top-level, will be respected
    // other Astro-accepted fields …
    mdastPlugins: [/* … */],
    hastPlugins: [/* … */]
  }
}

دليل استبدال سريع لإضافات remark الشائعة

إضافة remark القديمة	علم ميزة Astro الجديد
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

استبدل اسم الإضافة بعلم features.* المقابل في تكوين Astro الخاص بك.

أفضل الممارسات عند نقل الإضافات إلى Sätteri

• نمط المصنع (Factory pattern) – أنشئ مثيلاً جديداً للإضافة لكل مستند لتجنب تسرب الحالة (state) بين الصفحات.
• العقد غير القابلة للتغيير (Immutable nodes) – لا تقم أبداً بتعديل عقدة في مكانها؛ بل أرجع كائن عقدة جديداً حتى يتمكن المُعالج من تتبع التغييرات بشكل صحيح.
• مساعدات الإدراج (Insert helpers) – استخدم ctx.insertBefore أو ctx.insertAfter عندما تحتاج إلى إضافة عقد متجاورة، بدلاً من قص الشجرة يدوياً.

اتباع هذه القواعد يحافظ على استقرار المُعالج ويمنع حدوث أخطاء يصعب تتبعها.

ما يجب مراقبته لاحقاً

لا تزال وثائق Astro تدرج ترتيب الإضافات القديم كافتراضي، لذا قد ترث المشاريع الجديدة هذا السلوك المعطل دون قصد. راقب إصدارات Astro القادمة بحثاً عن إصلاح مدمج محتمل يعيد ترتيب إضافة heading-ID الداخلية. في هذه الأثناء، الخطوات المذكورة أعلاه هي الطريقة الوحيدة الموثوقة لاستعادة عرض الرياضيات، ومرابط العناوين، وخيارات Markdown المخصصة بعد الانتقال إلى Astro 7.

الخلاصة: يتطلب الانتقال إلى محرك Sätteri في Astro 7 نقل معالجة الرياضيات إلى mdastPlugins ، وتقديم إضافة slug قبل الـ autolinks، ورفع أي إعدادات markdown إضافية خارج كائن المُعالج؛ وبمجرد إجراء هذه التعديلات الثلاثة، ستعمل معادلات موقعك وروابط التنقل وميزات Markdown المخصصة كما كانت من قبل.