Astro 7 کا Rust پر مبنی Sätteri markdown engine پر منتقلی ان سائٹس کے لیے ایک ہموار اپ گریڈ کے بجائے تین طرفہ ڈراونا خواب بن گئی ہے جو ریاضی (math)، ہیڈنگ اینکرز (heading anchors)، اور کسٹم کنفیگریشن پر انحصار کرتی ہیں۔ Inline equations اب بھی کام کرتی ہیں، لیکن display-math بلاکس سادہ ٹیکسٹ کوڈ اسنیپٹس کے طور پر نظر آتے ہیں، ہیڈنگ IDs غائب ہو جاتی ہیں، اور Astro config میں آپ جو بھی اضافی آپشنز شامل کرتے ہیں انہیں خاموشی سے نظر انداز کر دیا جاتا ہے۔ وہ ڈویلپرز جو پچھلے Astro ریلیز سے مائیگریٹ کر رہے ہیں، انہیں اب پلگ انز کو دوبارہ لکھنا پڑے گا ورنہ ٹوٹے ہوئے صفحات (broken pages) کا خطرہ ہے۔

یہ تبدیلی کیوں اہم ہے

نیا انجن صارف کے فراہم کردہ کسی بھی پلگ ان سے پہلے ایک بلٹ ان سنٹیکس ہائی لائٹر (syntax highlighter) چلاتا ہے اور صرف تین ٹاپ لیول کنفیگریشن فیلڈز کو قبول کرتا ہے۔ یہ انتخاب اس طریقے سے ٹکراتے ہیں جس کے ذریعے زیادہ تر Astro پروجیکٹس فیچرز شامل کرتے ہیں: remark (MDAST) اور rehype (HAST) پلگ انز کے ذریعے جو ہائی لائٹنگ کے بعد چلنے کی توقع رکھتے ہیں، اور ایک پرمیسیو (permissive) کنفیگ آبجیکٹ کے ذریعے جو بنیادی markdown پارسر تک منتقل ہوتا ہے۔

اس کا اثر ان تمام صفحات پر نظر آتا ہے جو LaTeX-style math کو عام مواد کے ساتھ ملا کر استعمال کرتے ہیں۔ Inline math ($a+b$) ٹھیک سے رینڈر ہوتی ہے، لیکن ایک display block ($$a+b$$) کو <pre> ٹیگ میں لپیٹ دیا جاتا ہے، جس سے فارمیٹ شدہ مساوات کے بجائے خام را مارک اپ (raw markup) نظر آتا ہے۔ ہیڈنگ اینکرز جو table-of-contents لنکس یا deep-linking کو ممکن بناتے ہیں، غائب ہو جاتے ہیں کیونکہ ID-generation پلگ ان بلٹ ان ID ہینڈلر سے پہلے چلتا ہے، جس کی وجہ سے autolink پلگ ان کے لیے کچھ نہیں بچتا۔ وہ ڈویلپرز جنہوں نے shikiConfig آبجیکٹ کے ذریعے Shiki syntax highlighter کو بہتر بنانے کی کوشش کی تھی، وہ دیکھتے ہیں کہ یہ سیٹنگ بغیر کسی نشان کے غائب ہو گئی ہے۔

تکنیکی حل

1. ہائی لائٹنگ سے پہلے ریاضی (math) کو رینڈر کریں

اس کی بنیادی وجہ آپریشنز کی ترتیب ہے: Sätteri کا ہائی لائٹر پہلے ٹیکسٹ پر قبضہ کر لیتا ہے، اور math بلاک کو سادہ کوڈ کے طور پر درجہ بندی کر دیتا ہے۔ ریاضی (math) کو دوبارہ حاصل کرنے کے لیے، پروسیسنگ کو MDAST لیئر (وہ abstract syntax tree جو HTML بننے سے پہلے markdown کی نمائندگی کرتا ہے) پر منتقل کریں۔ کسی بھی HAST-level math پلگ ان کو اس کے MDAST متبادل سے بدل دیں اور انہیں ہائی لائٹر مرحلے سے پہلے چلائیں۔ عملی طور پر، remark-math پلگ انز کو ایسے ورژن سے بدل دیں جو markdown parsing مرحلے کے ساتھ منسلک ہو، پھر ہائی لائٹر کو پہلے سے تبدیل شدہ math nodes پر کام کرنے دیں۔

2. ہیڈنگ-ID پلگ انز کی ترتیب بدلیں

ہیڈنگ IDs ایک بلٹ ان پلگ ان کے ذریعے تیار کی جاتی ہیں جو اب صارف کے پلگ انز کے بعد چلتا ہے۔ کسٹم ID یا slug جنریٹرز کو پلگ ان لسٹ میں سب سے اوپر لے جائیں تاکہ وہ پہلے چلیں۔ اینکر لنکس کو بحال کرنے والی ایک عام ترتیب کچھ اس طرح ہے:

  1. slug/ID پلگ ان
  2. autolink پلگ ان
  3. کوئی بھی دوسرا remark پلگ ان

IDs کے شروع میں ہی موجود ہونے سے، autolink پلگ ان مطلوبہ <a> عناصر منسلک کر سکتا ہے، اور table-of-contents صحیح حصوں کی طرف اشارہ کرے گا۔

3. Sätteri کے سخت کنفیگ اسکیما (config schema) کا احترام کریں

Sätteri Astro markdown کنفیگریشن میں صرف تین فیلڈز کو تسلیم کرتا ہے۔ اس کے علاوہ کچھ بھی، جیسے کہ shikiConfig، خاموشی سے نظر انداز کر دیا جاتا ہے۔ کسٹم تھیمز یا ہائی لائٹر کی تبدیلیوں کو برقرار رکھنے کے لیے، ان سیٹنگز کو Astro config ہائیرارکی میں مناسب سطح پر منتقل کریں۔

فوری متبادل گائیڈ

اگر آپ ایک کلاسک 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) – صفحات کے درمیان ڈیٹا کے اخراج (data leakage) سے بچنے کے لیے ہر صفحے کے لیے ایک نیا اسٹیٹ آبجیکٹ بنائیں۔
  • غیر متبدل نوڈز (Immutable nodes) – جب آپ کو تبدیلی کی ضرورت ہو تو ایک نیا نوڈ واپس کریں؛ موجودہ نوڈ میں تبدیلی کرنے سے بعد کے پروسیسنگ مراحل خراب ہو سکتے ہیں۔
  • کوئی روٹ فرگمنٹس نہیں (No root fragments) – ٹاپ لیول فرگمنٹ نوڈ بنانے کے بجائے فراہم کردہ انسرشن ہیلپرز (insertion helpers) کے ذریعے سبلنگز (siblings) شامل کریں۔

جب آپ کسی موجودہ پلگ ان کو ڈھالیں، تو README کے مثال کے آؤٹ پٹ پر بھروسہ نہ کریں۔ اصل پلگ ان کے HTML کو رینڈر کریں، اس مارک اپ کو کیپچر کریں، اور اسے اپنے Sätteri-مطابقت پذیر ورژن کے لیے بطور حوالہ استعمال کریں۔

خلاصہ

Astro 7 کے Sätteri انجن سے رفتار تو بڑھتی ہے لیکن یہ markdown پروسیسنگ چین کی ترتیب کو تبدیل کرنے پر مجبور کرتا ہے: MDAST لیول پر math کو رینڈر کریں، heading-ID پلگ انز کو شروع میں رکھیں، اور کنفیگریشن کو تین منظور شدہ فیلڈز تک محدود رکھیں۔ feature-flag میپنگ پر عمل کریں، single-pass اور immutable-node کے قواعد کی پابندی کریں، اور آپ math، anchors، اور وہ custom theming بحال کر لیں گے جس پر آپ کی سائٹ کا انحصار ہے۔ محنت شروع میں کرنی ہوگی؛ لیکن اس کا فائدہ ایک زیادہ قابلِ پیش گوئی اور تیز رفتار markdown پائپ لائن کی صورت میں ملے گا۔