Astro 7-এর Rust-ভিত্তিক Sätteri markdown ইঞ্জিনে পরিবর্তনের ফলে display-math ব্লকগুলো সাধারণ কোডে পরিণত হচ্ছে, heading anchor মুছে যাচ্ছে এবং custom markdown অপশনগুলো বাদ পড়ে যাচ্ছে – যারা আপডেট করেছেন এবং এখন তাদের সাইটে ভাঙা সমীকরণ (broken equations) দেখছেন, তাদের জন্য এটি একটি বড় সমস্যা।

আপনি যদি LaTeX-style math, স্বয়ংক্রিয় heading link বা কাস্টম markdown plugin-এর ওপর নির্ভর করেন, তবে এই আপগ্রেড আপনার কন্টেন্টকে অপাঠ্য এবং নেভিগেশনকে অকেজো করে দিতে পারে, তাই এটি দ্রুত সমাধান করা অত্যন্ত জরুরি।

কেন আপগ্রেড করার ফলে সমস্যা তৈরি হয়েছে

Astro এখন তার কোর Markdown processor হিসেবে Sätteri ব্যবহার করে। Sätteri প্লাগইনগুলো প্রয়োগ করার ক্রম পরিবর্তন করে দেয়: এটি আপনার কনফিগার করা HTML-AST (HAST) প্লাগইনগুলোর আগেই syntax highlighting রান করে। এই পরিবর্তনের ফলে তিনটি সাধারণ প্যাটার্ন কাজ করা বন্ধ করে দেয়:

  • Display math – $$ … $$ দিয়ে ঘেরা ব্লকগুলোকে সাধারণ কোড হিসেবে গণ্য করা হয় কারণ highlighter আগে রান করে।
  • Heading anchors – যে প্লাগইনগুলো slug (URL-friendly ID) তৈরি করে এবং তারপর সেই heading-গুলোকে autolink করে, তারা আর ID খুঁজে পায় না, ফলে লিঙ্কগুলো তৈরি হয় না।
  • Custom options – আপনি সরাসরি Sätteri processor-এ যে অতিরিক্ত সেটিংসগুলো দিয়েছিলেন তা উপেক্ষা করা হয়; Astro শুধুমাত্র তিনটি পূর্বনির্ধারিত (predefined) ফিল্ড পাস করে।

সুনির্দিষ্ট সমাধানসমূহ

১. HTML-AST-এর পরিবর্তে markdown-AST (MDAST)-এ math রেন্ডার করুন

Astro-র markdown pipeline-এ দুটি plugin slot রয়েছে:

  • 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
  }
}

স্ট্যান্ডার্ড সেটআপে একটি 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) দিতে পারবে।

৩. Astro markdown অবজেক্টের টপ লেভেলে অতিরিক্ত কনফিগারেশন রাখুন

Astro শুধুমাত্র তিনটি নির্দিষ্ট ফিল্ড Sätteri processor-এ পাঠায়। আপনি processor-এর ভেতরে যা কিছু নেস্ট (nest) করবেন (উদাহরণস্বরূপ একটি shikiConfig অবজেক্ট), তা বাদ পড়ে যাবে। সেই অতিরিক্ত সেটিংসগুলোকে markdown কনফিগারেশনের টপ লেভেলে নিয়ে যান।

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

সাধারণ remark প্লাগইনগুলোর জন্য দ্রুত রিপ্লেসমেন্ট গাইড

পুরাতন 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-এ প্লাগইন নামের পরিবর্তে সংশ্লিষ্ট features.* ফ্ল্যাগটি ব্যবহার করুন।

Sätteri-তে প্লাগইন পোর্ট করার সময় সেরা অনুশীলনসমূহ (Best practices)

  • Factory pattern – পেজগুলোর মধ্যে স্টেট লিক হওয়া এড়াতে প্রতিটি ডকুমেন্টের জন্য একটি নতুন plugin instance তৈরি করুন।
  • Immutable nodes – কোনো নোডকে সরাসরি পরিবর্তন (mutate) করবেন না; একটি নতুন node object রিটার্ন করুন যাতে processor সঠিকভাবে পরিবর্তনগুলো ট্র্যাক করতে পারে।
  • Insert helpers – ম্যানুয়ালি tree splice করার পরিবর্তে sibling node যোগ করার প্রয়োজন হলে ctx.insertBefore বা ctx.insertAfter ব্যবহার করুন।

এই নিয়মগুলো অনুসরণ করলে processor স্থিতিশীল থাকে এবং শনাক্ত করা কঠিন এমন বাগ (bug) প্রতিরোধ করা যায়।

পরবর্তী করণীয় বা যা খেয়াল রাখতে হবে

Astro-র ডকুমেন্টেশনে এখনও ডিফল্ট হিসেবে পুরনো প্লাগইন ক্রমটি দেখানো হচ্ছে, তাই নতুন প্রজেক্টগুলোতে অনিচ্ছাকৃতভাবে এই সমস্যাটি দেখা দিতে পারে। ইন্টারনাল heading-ID প্লাগইনটির ক্রম পরিবর্তন করে একটি বিল্ট-ইন ফিক্স আনা হচ্ছে কি না, তা দেখার জন্য আসন্ন Astro রিলিজগুলোর দিকে নজর রাখুন। আপাতত, Astro 7-এ যাওয়ার পর math rendering, heading anchor এবং custom markdown অপশনগুলো ফিরিয়ে আনার একমাত্র নির্ভরযোগ্য উপায় হলো উপরের ধাপগুলো অনুসরণ করা।

সারকথা (Takeaway): Astro 7-এর Sätteri ইঞ্জিনে সুইচ করার জন্য math হ্যান্ডলিং mdastPlugins-এ নিয়ে যাওয়া, autolink-এর আগে slug plugin-টিকে সামনে রাখা এবং processor অবজেক্ট থেকে অতিরিক্ত markdown সেটিংসগুলোকে সরিয়ে টপ লেভেলে নিয়ে আসা প্রয়োজন; এই তিনটি সমন্বয় করার পর আপনার সাইটের সমীকরণ, নেভিগেশন লিঙ্ক এবং কাস্টম markdown ফিচারগুলো আগের মতোই কাজ করবে।