Astro 7-এর Rust-ভিত্তিক Sätteri markdown ইঞ্জিনে পরিবর্তনটি গণিত (math), হেডিং অ্যাঙ্কর (heading anchors) এবং কাস্টম কনফিগারেশনের ওপর নির্ভরশীল সাইটগুলোর জন্য একটি মসৃণ আপগ্রেড থেকে তিনগুণ দুঃস্বপ্নে পরিণত হয়েছে। ইনলাইন ইকুয়েশনগুলো (inline equations) এখনও কাজ করে, কিন্তু ডিসপ্লে-ম্যাথ ব্লকগুলো (display-math blocks) সাধারণ টেক্সট কোড স্নিপেট হিসেবে দেখাচ্ছে, হেডিং আইডিগুলো (heading IDs) হারিয়ে যাচ্ছে এবং Astro কনফিগারেশনে আপনি যে অতিরিক্ত অপশনগুলো যোগ করেন সেগুলো নিঃশব্দে উপেক্ষা করা হচ্ছে। যারা আগের Astro রিলিজ থেকে মাইগ্রেট করছেন, তাদের এখন প্লাগইনগুলো পুনরায় লিখতে হচ্ছে অথবা ভাঙা পেজের ঝুঁকি নিতে হচ্ছে।

কেন এই পরিবর্তনটি গুরুত্বপূর্ণ

নতুন ইঞ্জিনটি ব্যবহারকারীর দেওয়া যেকোনো প্লাগইনের আগে একটি বিল্ট-ইন সিনট্যাক্স হাইলাইটার (syntax highlighter) চালায় এবং এটি মাত্র তিনটি টপ-লেভেল কনফিগারেশন ফিল্ড গ্রহণ করে। এই পছন্দগুলো বেশিরভাগ Astro প্রজেক্টে ফিচার যোগ করার পদ্ধতির সাথে সাংঘর্ষিক: remark (MDAST) এবং rehype (HAST) প্লাগইনের মাধ্যমে ফিচার যোগ করা হয় যা হাইলাইটিংয়ের পরে চলার কথা থাকে, এবং একটি পারমিসিভ (permissive) কনফিগারেশন অবজেক্টের মাধ্যমে যা আন্ডারলাইং মার্কডাউন পার্সারের কাছে পাস করা হয়।

এর প্রভাব সেই সব পেজে দেখা যায় যেখানে LaTeX-স্টাইলের গণিত এবং সাধারণ কন্টেন্টের মিশ্রণ রয়েছে। ইনলাইন ম্যাথ ($a+b$) ঠিকঠাক রেন্ডার হয়, কিন্তু একটি ডিসপ্লে ব্লক ($$a+b$$) একটি <pre> ট্যাগের মধ্যে মুড়িয়ে দেওয়া হয়, যা ফরম্যাট করা ইকুয়েশনের পরিবর্তে র (raw) মার্কআপ দেখায়। হেডিং অ্যাঙ্করগুলো, যা টেবিল-অফ-কন্টেন্ট লিঙ্ক বা ডিপ-লিঙ্কিংয়ের জন্য ব্যবহৃত হয়, সেগুলো অদৃশ্য হয়ে যায় কারণ আইডি-জেনারেটর প্লাগইনটি বিল্ট-ইন আইডি হ্যান্ডলারের আগে চলে, ফলে অটোলিংক (autolink) প্লাগইনের ধরার মতো কিছু থাকে না। যেসব ডেভেলপার shikiConfig অবজেক্ট দিয়ে Shiki সিনট্যাক্স হাইলাইটারকে সূক্ষ্মভাবে টিউন করার চেষ্টা করেছিলেন, তারা দেখতে পান যে সেটি কোনো চিহ্ন ছাড়াই হারিয়ে গেছে।

প্রযুক্তিগত সমাধানসমূহ

১. হাইলাইটিংয়ের আগে গণিত রেন্ডার করুন

মূল কারণ হলো অপারেশনের ক্রম (order of operations): Sätteri-এর হাইলাইটার প্রথমে টেক্সটটি দখল করে নেয় এবং গণিত ব্লককে সাধারণ কোড হিসেবে শ্রেণীবদ্ধ করে। গণিতকে পুনরায় ফিরে পেতে প্রসেসিংকে MDAST লেয়ারে (মার্কডাউন HTML হওয়ার আগে যে অ্যাবস্ট্রাক্ট সিনট্যাক্স ট্রি তৈরি করে) সরিয়ে নিন। যেকোনো HAST-লেভেল ম্যাথ প্লাগইনকে তাদের MDAST সমতুল্য প্লাগইন দিয়ে প্রতিস্থাপন করুন এবং হাইলাইটার ধাপের আগে সেগুলো চালান। বাস্তবে, remark-math প্লাগইনগুলোকে এমন একটি ভার্সন দিয়ে পরিবর্তন করুন যা মার্কডাউন পার্সিং পর্যায়ে যুক্ত হয়, তারপর হাইলাইটারকে ইতিমধ্যে রূপান্তরিত ম্যাথ নোডগুলোর ওপর কাজ করতে দিন।

২. হেডিং-ID প্লাগইনগুলোর ক্রম পরিবর্তন করুন

হেডিং আইডিগুলো একটি বিল্ট-ইন প্লাগইন দ্বারা তৈরি করা হয় যা এখন ব্যবহারকারীর প্লাগইনগুলোর পরে কার্যকর হয়। কাস্টম আইডি বা স্ল্যাগ (slug) জেনারেটরগুলোকে প্লাগইন তালিকার শীর্ষে নিয়ে আসুন যাতে সেগুলো প্রথমে চলে। অ্যাঙ্কর লিঙ্কগুলো পুনরুদ্ধার করার জন্য একটি আদর্শ ক্রম হলো:

১. slug/ID প্লাগইন ২. autolink প্লাগইন ৩. অন্য যেকোনো remark প্লাগইন

আইডিগুলো আগেভাগে সেট হয়ে গেলে, autolink প্লাগইনটি প্রত্যাশিত <a> এলিমেন্টগুলো যুক্ত করতে পারে এবং টেবিল-অফ-কন্টেন্ট সঠিক সেকশনগুলোর দিকে নির্দেশ করবে।

৩. Sätteri-এর কঠোর কনফিগারেশন স্কিমা মেনে চলুন

Astro মার্কডাউন কনফিগারেশনে Sätteri মাত্র তিনটি ফিল্ড গ্রহণ করে। অন্য যেকোনো কিছু, যেমন shikiConfig, নিঃশব্দে বাদ পড়ে যায়। কাস্টম থিম বা হাইলাইটার টিউনগুলো সচল রাখতে, সেই সেটিংসগুলোকে Astro কনফিগারেশন হায়ারার্কির সঠিক স্তরে সরিয়ে নিন।

দ্রুত প্রতিস্থাপনের নির্দেশিকা

আপনি যদি একটি ক্লাসিক Astro মার্কডাউন স্ট্যাক পোর্ট করছেন, তবে পুরনো 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) – কোনো পরিবর্তন প্রয়োজন হলে একটি নতুন নোড রিটার্ন করুন; বিদ্যমান কোনো নোড পরিবর্তন (mutate) করলে পরবর্তী প্রসেসিং ধাপগুলো ভেঙে যেতে পারে।
  • কোনো রুট ফ্র্যাগমেন্ট নয় (No root fragments) – একটি টপ-লেভেল ফ্র্যাগমেন্ট নোড তৈরি করার পরিবর্তে প্রদত্ত ইনসারশন হেল্পারগুলোর মাধ্যমে সিবলিং (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 পাইপলাইন।