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

Astro 7 का Rust-आधारित Sätteri markdown इंजन पर स्विच होना display-math ब्लॉक्स को plain code में बदल रहा है, heading anchors को हटा रहा है और custom markdown options को हटा रहा है – यह उन सभी के लिए एक बड़ी समस्या है जिन्होंने अपग्रेड किया है और अब अपनी साइट पर टूटी हुई equations देख रहे हैं।

यदि आप LaTeX-style math, automatic heading links या bespoke markdown plugins पर निर्भर हैं, तो यह अपग्रेड आपकी सामग्री को अपठनीय और आपके नेविगेशन को अनुपयोगी बना सकता है, इसलिए इसे जल्दी ठीक करना आवश्यक है।

अपग्रेड ने चीज़ों को क्यों बिगाड़ दिया

Astro अब Sätteri को अपने core Markdown processor के रूप में चलाता है। Sätteri उस क्रम को बदल देता है जिसमें plugins लागू किए जाते हैं: यह आपके द्वारा कॉन्फ़िगर किए गए HTML-AST (HAST) plugins से पहले syntax highlighting चलाता है। इस बदलाव का मतलब है कि तीन सामान्य पैटर्न काम करना बंद कर देते हैं:

• Display math – $$ … $$ द्वारा delimited ब्लॉक्स को साधारण code माना जाता है क्योंकि highlighter पहले चलता है।
• Heading anchors – वे plugins जो slugs (URL-friendly IDs) जनरेट करते हैं और फिर उन headings को autolink करते हैं, वे अब IDs को नहीं देख पाते, इसलिए links कभी नहीं बनते।
• Custom options – कोई भी अतिरिक्त settings जो आपने सीधे Sätteri processor में पास की थीं, उन्हें अनदेखा कर दिया जाता है; Astro केवल तीन predefined fields को ही आगे भेजता है।

ठोस समाधान

1. HTML-AST के बजाय markdown-AST (MDAST) पर math को render करें

Astro के markdown pipeline में दो plugin slots होते हैं:

• mdastPlugins – HTML बनने से पहले parsed markdown tree पर चलते हैं।
• hastPlugins – conversion के बाद 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 का क्रम बदलें

Standard setups में एक slug generator के बाद autolink plugin इंस्टॉल किया जाता है। Astro में, built-in heading-ID plugin आपकी list के बाद चलता है, जिससे autolink plugin के पास attach करने के लिए कुछ नहीं बचता। list में 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. Extra configuration को Astro markdown object के top level पर रखें

Astro केवल तीन विशिष्ट fields को Sätteri processor को भेजता है। आप processor के अंदर जो कुछ भी nest करते हैं (उदाहरण के लिए एक shikiConfig object), उसे हटा दिया जाता है। उन extra settings को markdown configuration के top level पर ले जाएँ।

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 पोर्ट करते समय सर्वोत्तम अभ्यास

• Factory pattern – पेजों के बीच state लीक होने से बचने के लिए प्रत्येक document के लिए एक नया plugin instance बनाएँ।
• Immutable nodes – किसी node को कभी भी in-place mutate न करें; एक नया node object return करें ताकि processor परिवर्तनों को सही ढंग से ट्रैक कर सके।
• Insert helpers – जब आपको sibling nodes जोड़ने की आवश्यकता हो, तो tree को मैन्युअल रूप से splice करने के बजाय ctx.insertBefore या ctx.insertAfter का उपयोग करें।

इन नियमों का पालन करने से processor स्थिर रहता है और कठिन-से-ट्रैक होने वाले bugs से बचाव होता है।

आगे क्या ध्यान रखें

Astro का documentation अभी भी पुराने plugin order को default के रूप में सूचीबद्ध करता है, इसलिए नए प्रोजेक्ट्स अनजाने में इस खराब व्यवहार को अपना सकते हैं। आने वाले Astro releases पर नज़र रखें, जिसमें संभवतः एक built-in fix हो सकता है जो internal heading-ID plugin के क्रम को बदल दे। इस बीच, Astro 7 पर जाने के बाद math rendering, heading anchors और custom markdown options को बहाल करने का एकमात्र विश्वसनीय तरीका ऊपर दिए गए चरण ही हैं।

मुख्य बात: Astro 7 के Sätteri engine पर स्विच करने के लिए math handling को mdastPlugins में ले जाना, autolinks से पहले slug plugin को आगे रखना, और किसी भी extra markdown settings को processor object से बाहर निकालना आवश्यक है; एक बार ये तीन समायोजन कर लिए जाने के बाद, आपकी साइट की equations, navigation links और custom markdown features पहले की तरह काम करने लगेंगे।