تغییر Astro 7 به موتور markdown مبتنی بر Rust یعنی Sätteri، باعث می‌شود بلوک‌های display-math به کد معمولی تبدیل شوند، لنگرهای عنوان (heading anchors) حذف شوند و گزینه‌های سفارشی markdown نادیده گرفته شوند؛ این موضوع برای هر کسی که آپگرید کرده و اکنون با معادلات شکسته در سایت خود مواجه است، یک مشکل بزرگ است.

اگر به ریاضیات سبک LaTeX، لینک‌های خودکار عنوان یا پلاگین‌های سفارشی markdown متکی هستید، این آپگرید می‌تواند محتوای شما را غیرقابل خواندن و ناوبری سایت را غیرقابل استفاده کند، بنابراین رفع سریع آن ضروری است.

چرا آپگرید باعث بروز مشکل شد

Astro اکنون Sätteri را به عنوان پردازشگر اصلی Markdown خود اجرا می‌کند. Sätteri ترتیب اعمال پلاگین‌ها را تغییر می‌دهد: این موتور، syntax highlighting را قبل از پلاگین‌های HTML-AST (HAST) که ممکن است پیکربندی کرده باشید، اجرا می‌کند. این تغییر باعث می‌شود سه الگوی رایج از کار بیفتند:

  • Display math – بلوک‌هایی که با $$ … $$ مشخص شده‌اند، به عنوان کد معمولی در نظر گرفته می‌شوند زیرا highlighter ابتدا اجرا می‌شود.
  • Heading anchors – پلاگین‌هایی که slug (شناسه‌های سازگار با URL) تولید می‌کنند و سپس آن عناوین را به‌صورت خودکار لینک می‌کنند (autolink)، دیگر شناسه‌ها را نمی‌بینند، بنابراین لینک‌ها هرگز ساخته نمی‌شوند.
  • Custom options – هر تنظیمات اضافی که مستقیماً به پردازشگر Sätteri ارسال کرده‌اید، نادیده گرفته می‌شود؛ Astro فقط سه فیلد از پیش تعریف شده را ارسال می‌کند.

راهکارهای عملی

۱. رندر کردن ریاضیات روی markdown-AST (MDAST) به جای HTML-AST

خط لوله (pipeline) markdown در Astro دارای دو جایگاه برای پلاگین است:

  • mdastPlugins – روی درخت markdown تجزیه‌شده، قبل از تبدیل شدن به HTML اجرا می‌شود.
  • hastPlugins – روی درخت HTML، پس از تبدیل اجرا می‌شود.

از آنجایی که highlighter قبل از hastPlugins اجرا می‌شود، ریاضیات به یک بلوک کد تبدیل می‌شود. پلاگین ریاضی خود را به mdastPlugins منتقل کنید.

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

تنظیمات استاندارد، ابتدا یک مولد slug و سپس یک پلاگین autolink را نصب می‌کنند. در Astro، پلاگین داخلی heading-ID بعد از لیست شما اجرا می‌شود و چیزی برای پلاگین autolink باقی نمی‌گذارد تا به آن متصل شود. پلاگین slug را در ابتدای لیست و سپس پلاگین autolink را قرار دهید.

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

اکنون هر عنوان یک ID دریافت می‌کند و پلاگین autolink می‌تواند آن را با لنگر (anchor) مناسب محصور کند.

۳. قرار دادن تنظیمات اضافی در سطح بالای (top level) شیء markdown در Astro

Astro فقط سه فیلد خاص را به پردازشگر Sätteri ارسال می‌کند. هر چیزی که داخل پردازشگر قرار دهید (برای مثال یک شیء shikiConfig) حذف می‌شود. آن تنظیمات اضافی را به سطح بالای پیکربندی markdown منتقل کنید.

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

راهنمای جایگزینی سریع برای پلاگین‌های رایج remark

پلاگین remark قدیمی پرچم ویژگی (feature flag) جدید Astro
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

نام پلاگین را با پرچم features.* مربوطه در تنظیمات Astro خود جایگزین کنید.

بهترین روش‌ها هنگام انتقال پلاگین‌ها به Sätteri

  • Factory pattern – برای هر سند یک نمونه (instance) جدید از پلاگین ایجاد کنید تا از نشت وضعیت (state leaking) بین صفحات جلوگیری شود.
  • Immutable nodes – هرگز یک گره (node) را در محل تغییر ندهید؛ یک شیء گره جدید برگردانید تا پردازشگر بتواند تغییرات را به درستی دنبال کند.
  • Insert helpers – زمانی که نیاز به افزودن گره‌های هم‌سطح (sibling nodes) دارید، به جای برش دادن (splicing) دستی درخت، از ctx.insertBefore یا ctx.insertAfter استفاده کنید.

رعایت این قوانین باعث پایداری پردازشگر شده و از باگ‌های سخت‌عیب‌یابی جلوگیری می‌کند.

آنچه باید در آینده زیر نظر داشته باشید

مستندات Astro هنوز ترتیب قدیمی پلاگین‌ها را به عنوان پیش‌فرض لیست می‌کنند، بنابراین پروژه‌های جدید ممکن است ناخواسته این رفتار خراب را به ارث ببرند. منتظر نسخه‌های آتی Astro باشید تا شاید یک اصلاح داخلی برای تغییر ترتیب پلاگین heading-ID ارائه شود. در این میان، مراحل بالا تنها راه قابل اعتماد برای بازیابی رندر ریاضیات، لنگرهای عنوان و گزینه‌های سفارشی markdown پس از مهاجرت به Astro 7 است.

نکته کلیدی: تغییر به موتور Sätteri در Astro 7 مستلزم انتقال مدیریت ریاضیات به mdastPlugins ، قرار دادن پلاگین slug قبل از autolinks، و خارج کردن تنظیمات اضافی markdown از شیء پردازشگر است؛ پس از انجام این سه تنظیم، معادلات سایت، لینک‌های ناوبری و ویژگی‌های سفارشی markdown شما مانند قبل کار خواهند کرد.