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

Astro 7 کا Rust پر مبنی Sätteri markdown engine پر منتقل ہونا display-math بلاکس کو سادہ کوڈ میں تبدیل کر رہا ہے، heading anchors کو ختم کر رہا ہے اور custom markdown options کو ضائع کر رہا ہے – یہ ان تمام لوگوں کے لیے ایک بڑی مشکل ہے جنہوں نے اپ گریڈ کیا ہے اور اب اپنی سائٹ پر ٹوٹے ہوئے (broken) مساواتیں (equations) دیکھ رہے ہیں۔

اگر آپ LaTeX-style math، خودکار heading links، یا مخصوص markdown plugins پر انحصار کرتے ہیں، تو یہ اپ گریڈ آپ کے مواد کو ناقابلِ فہم اور آپ کی نیویگیشن کو ناقابلِ استعمال بنا سکتا ہے، اس لیے اسے جلد از جلد ٹھیک کرنا ضروری ہے۔

اپ گریڈ نے چیزوں کو کیوں خراب کیا

Astro اب Sätteri کو اپنے بنیادی Markdown processor کے طور پر چلاتا ہے۔ Sätteri اس ترتیب کو تبدیل کر دیتا ہے جس میں plugins لاگو کیے جاتے ہیں: یہ ان HAST (HTML-AST) plugins سے پہلے syntax highlighting چلاتا ہے جو آپ نے کنفیگر کیے ہوں گے۔ اس تبدیلی کا مطلب ہے کہ تین عام پیٹرن کام کرنا بند کر دیتے ہیں:

• Display math – $$ … $$ سے گھیرے ہوئے بلاکس کو عام کوڈ سمجھا جاتا ہے کیونکہ highlighter پہلے چلتا ہے۔
• Heading anchors – وہ plugins جو slugs (URL-friendly IDs) تیار کرتے ہیں اور پھر ان headings کو خودکار طور پر لنک کرتے ہیں، اب انہیں IDs نظر نہیں آتیں، اس لیے لنکس کبھی نہیں بن پاتے۔
• Custom options – کوئی بھی اضافی سیٹنگز جو آپ نے براہ راست Sätteri processor میں پاس کی تھیں، انہیں نظر انداز کر دیا جاتا ہے؛ Astro صرف تین پہلے سے طے شدہ (predefined) fields کو آگے بھیجتا ہے۔

ٹھوس حل (The concrete fixes)

1. HTML-AST کے بجائے markdown-AST (MDAST) پر math کو رینڈر کریں

Astro کے markdown pipeline میں دو plugin slots ہیں:

• mdastPlugins – HTML بننے سے پہلے parsed markdown tree پر چلتے ہیں۔
• hastPlugins – کنورژن کے بعد HTML tree پر چلتے ہیں۔

چونکہ highlighter hastPlugins سے پہلے چلتا ہے، اس لیے math ایک code block میں تبدیل ہو جاتا ہے۔ اپنے math plugin کو mdastPlugins میں منتقل کریں۔

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

2. Headings کے لیے slug اور autolink plugins کی ترتیب تبدیل کریں

معیاری سیٹ اپ میں ایک slug generator کے بعد autolink plugin انسٹال کیا جاتا ہے۔ Astro میں، بلٹ ان heading-ID plugin آپ کی فہرست کے بعد چلتا ہے، جس کی وجہ سے autolink plugin کے پاس منسلک کرنے کے لیے کچھ نہیں بچتا۔ فہرست میں پہلے slug plugin رکھیں، پھر autolink plugin۔

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

اب ہر heading کو ایک ID مل جاتی ہے اور autolink plugin اسے مناسب anchor کے ساتھ لپیٹ (wrap) سکتا ہے۔

3. اضافی کنفیگریشن کو Astro markdown object کے ٹاپ لیول پر رکھیں

Astro صرف تین مخصوص fields کو Sätteri processor کو بھیجتا ہے۔ آپ processor کے اندر جو کچھ بھی نےسٹ (nest) کرتے ہیں (مثال کے طور پر ایک shikiConfig object) اسے نکال دیا جاتا ہے۔ ان اضافی سیٹنگز کو markdown کنفیگریشن کے ٹاپ لیول پر منتقل کریں۔

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

عام remark plugins کے لیے فوری ریپلیسمنٹ گائیڈ

پرانا remark plugin	نیا Astro feature flag
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

اپنی Astro config میں plugin کے نام کو متعلقہ features.* flag سے بدل دیں۔

Sätteri میں plugins منتقل کرتے وقت بہترین طریقے (Best practices)

• Factory pattern – صفحات کے درمیان اسٹیٹ (state) کے اخراج (leak) سے بچنے کے لیے ہر دستاویز کے لیے ایک نیا plugin instance بنائیں۔
• Immutable nodes – کسی بھی node کو وہیں تبدیل (mutate) نہ کریں؛ ایک نیا node object واپس کریں تاکہ processor تبدیلیوں کو درست طریقے سے ٹریک کر سکے۔
• Insert helpers – جب آپ کو سگبیلننگ (sibling) nodes شامل کرنے کی ضرورت ہو تو ٹری کو دستی طور پر splice کرنے کے بجائے ctx.insertBefore یا ctx.insertAfter کا استعمال کریں۔

ان قواعد پر عمل کرنے سے processor مستحکم رہتا ہے اور مشکل سے ٹریک ہونے والے بگ (bugs) سے بچا جا سکتا ہے۔

آگے کیا نظر رکھنا ہے

Astro کی دستاویزات اب بھی پرانی plugin ترتیب کو ڈیفالٹ کے طور پر درج کرتی ہیں، اس لیے نئے پروجیکٹس غیر ارادی طور پر خراب طرزِ عمل (broken behavior) اپنا سکتے ہیں۔ آنے والی Astro ریلیزز پر نظر رکھیں تاکہ ممکنہ بلٹ ان فکس مل سکے جو اندرونی heading-ID plugin کی ترتیب کو دوبارہ ترتیب دے دے۔ اس دوران، Astro 7 پر منتقل ہونے کے بعد math rendering، heading anchors اور custom markdown options کو بحال کرنے کا واحد قابلِ اعتماد طریقہ اوپر دیے گئے اقدامات ہیں۔

خلاصہ (Takeaway): Astro 7 کے Sätteri engine پر منتقل ہونے کے لیے math handling کو mdastPlugins میں منتقل کرنا، autolinks سے پہلے slug plugin کو آگے رکھنا، اور کسی بھی اضافی markdown سیٹنگز کو processor object سے نکال کر باہر لانا ضروری ہے؛ ایک بار جب یہ تینوں تبدیلیاں کر لی جائیں گی، تو آپ کی سائٹ کی مساواتیں، نیویگیشن لنکس اور custom markdown فیچرز پہلے کی طرح کام کرنے لگیں گے۔