Astro 7 च्या Rust-आधारित Sätteri markdown इंजिनमधील बदलामुळे, गणित (math), हेडिंग अँकर्स (heading anchors) आणि कस्टम कॉन्फिगरेशनवर अवलंबून असलेल्या साइट्ससाठी एक सोपा अपग्रेड तीन पटीने वाढलेल्या nightmare मध्ये बदलला आहे. Inline equations अजूनही काम करतात, परंतु display-math ब्लॉक्स साध्या मजकुरासारखे (plain-text code snippets) दिसतात, heading IDs गायब होतात आणि Astro config मध्ये तुम्ही जोडलेले कोणतेही अतिरिक्त पर्याय शांतपणे दुर्लक्षित केले जातात. जे डेव्हलपर्स आधीच्या Astro releases मधून स्थलांतरित होत आहेत, त्यांना आता प्लगइन्स पुन्हा लिहावे लागतील किंवा तुटलेल्या पेजेसचा धोका पत्करावा लागेल.

हा बदल का महत्त्वाचा आहे

नवीन इंजिन कोणत्याही युजर-सप्लायड प्लगइन्सच्या आधी एक इन-बिल्ट सिंटॅक्स हायलाइटर (syntax highlighter) चालवते आणि फक्त तीन टॉप-लेव्हल कॉन्फिगरेशन फील्ड्स स्वीकारते. हे पर्याय बहुतेक Astro प्रोजेक्ट्समध्ये फीचर्स जोडण्याच्या पद्धतीशी विसंगत आहेत: जे remark (MDAST) आणि rehype (HAST) प्लगइन्सद्वारे फीचर्स जोडतात (ज्यांची अपेक्षा हायलाइटिंगनंतर चालण्याची असते) आणि एका permissive config ऑब्जेक्टद्वारे फीचर्स जोडतात जो मूळ markdown पार्सरकडे पाठवला जातो.

याचा परिणाम अशा कोणत्याही पेजवर दिसून येतो जिथे LaTeX-style math आणि नियमित मजकूर एकत्र असतो. Inline math ($a+b$) व्यवस्थित रेंडर होते, परंतु display block ($$a+b$$) एका <pre> टॅगमध्ये गुंडाळला जातो, ज्यामुळे फॉरमॅट केलेल्या समीकरणाऐवजी रॉ मार्कअप (raw markup) दिसतो. Table-of-contents लिंक्स किंवा deep-linking साठी वापरले जाणारे heading anchors गायब होतात, कारण ID-generation प्लगइन इन-बिल्ट ID हँडलरच्या आधी चालते, ज्यामुळे autolink प्लगइनला पकडण्यासाठी काहीही उरत नाही. ज्या डेव्हलपर्सनी shikiConfig ऑब्जेक्ट वापरून Shiki syntax highlighter ला फाईन-ट्यून करण्याचा प्रयत्न केला, त्यांना ते सेटिंग कोणताही मागमूस न सोडता गायब झाल्याचे आढळले.

तांत्रिक उपाय

1. हायलाइटिंगपूर्वी गणित रेंडर करा

याचे मूळ कारण क्रमाचा (order of operations) आहे: Sätteri चा हायलाइटर मजकूर आधी घेतो आणि गणितीय ब्लॉकला साध्या कोड (plain code) म्हणून वर्गीकृत करतो. गणित पुन्हा मिळवण्यासाठी, प्रोसेसिंग MDAST लेयरकडे (HTML मध्ये रूपांतरित होण्यापूर्वी markdown दर्शवणारा abstract syntax tree) वळवा. कोणत्याही HAST-level math प्लगइन्सच्या जागी त्यांचे MDAST समकक्ष (equivalents) वापरा आणि हायलाइटर स्टेपच्या आधी ते चालवा. व्यवहारात, remark-math प्लगइन्सच्या जागी असे व्हर्जन वापरा जे markdown parsing स्टेजमध्ये हुक होते, आणि त्यानंतर हायलाइटरला आधीच रूपांतरित केलेल्या math nodes वर काम करू द्या.

2. हेडिंग-ID प्लगइन्सचा क्रम बदला

Heading IDs एका इन-बिल्ट प्लगइनद्वारे तयार केले जातात जे आता युजर प्लगइन्सच्या नंतर चालते. कस्टम ID किंवा slug जनरेटर्सना प्लगइन लिस्टमध्ये सर्वात वर न्या जेणेकरून ते आधी चालतील. अँकर लिंक्स पुन्हा स्थापित करणारा एक सामान्य क्रम असा दिसतो:

  1. slug/ID plugin
  2. autolink plugin
  3. इतर कोणतेही remark plugins

ID सुरुवातीलाच उपलब्ध असल्यास, autolink प्लगइन अपेक्षित <a> एलिमेंट्स जोडू शकतो आणि table-of-contents योग्य विभागांकडे निर्देशित करेल.

3. Sätteri च्या कडक कॉन्फिगरेशन स्कीमाचे पालन करा

Sätteri Astro markdown कॉन्फिगरेशनमध्ये फक्त तीन फील्ड्स स्वीकारते. shikiConfig सारखे इतर काहीही असल्यास, ते शांतपणे काढून टाकले जाते. कस्टम थीम्स किंवा हायलाइटरमधील बदल टिकवून ठेवण्यासाठी, ते सेटिंग्ज Astro config च्या योग्य हायरार्कीमध्ये हलवा.

जलद रिप्लेसमेंट गाईड

जर तुम्ही क्लासिक Astro markdown स्टॅक पोर्ट करत असाल, तर जुने remark प्लगइन्स Sätteri ला समजणाऱ्या नवीन feature flags ने बदला:

  • 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) – जेव्हा तुम्हाला बदल करायचा असेल तेव्हा नवीन नोड रिटर्न करा; अस्तित्वात असलेल्या नोडमध्ये बदल (mutating) केल्यास पुढील प्रोसेसिंग स्टेप्समध्ये बिघाड होऊ शकतो.
  • रूट फ्रॅगमेंट्स नकोत (No root fragments) – टॉप-लेव्हल फ्रॅगमेंट नोड तयार करण्याऐवजी प्रदान केलेल्या इन्सर्शन हेल्पर्सद्वारे सिब्लिंग्स (siblings) इन्सर्ट करा.

जेव्हा तुम्ही एखादा अस्तित्वात असलेला प्लगइन ॲडॅप्ट करता, तेव्हा README मधील उदाहरण आउटपुटवर अवलंबून राहू नका. मूळ प्लगइनचा HTML रेंडर करा, तो मार्कअप कॅप्चर करा आणि तुमच्या Sätteri-सुसंगत व्हर्जनसाठी संदर्भ बिंदू (reference point) म्हणून त्याचा वापर करा.

निष्कर्ष

Astro 7 च्या Sätteri इंजिनमुळे वेग मिळतो, परंतु यामुळे markdown प्रोसेसिंग चेनमध्ये फेररचना करणे अनिवार्य होते: MDAST लेव्हलवर math रेंडर करा, heading-ID प्लगइन्सना सुरुवातीला ठेवा आणि कॉन्फिगरेशन केवळ तीन स्वीकारार्ह फील्ड्सपुरते मर्यादित ठेवा. feature-flag मॅपिंगचे अनुसरण करा, single-pass आणि immutable-node नियमांचे पालन करा, आणि तुम्ही तुमच्या साइटवर अवलंबून असलेली math, anchors आणि custom theming पुन्हा पूर्ववत करू शकाल. ही मेहनत सुरुवातीला घ्यावी लागेल; परंतु त्याचे फळ अधिक निश्चित आणि वेगवान markdown पाइपलाइनच्या स्वरूपात मिळेल.