המעבר של Astro 7 למנוע ה-markdown מבוסס ה-Rust בשם Sätteri הפך שדרוג חלק לסיוט משולש עבור אתרים המסתמכים על מתמטיקה, עוגני כותרות (heading anchors) וקונפיגורציה מותאמת אישית. משוואות inline עדיין עובדות, אך בלוקים של display-math מופיעים כקטעי קוד בטקסט רגיל, מזהי כותרות (heading IDs) נעלמים, וכל אפשרות נוספת שמוסיפים לקונפיגורציה של Astro פשוט נתעלמת בשקט. מפתחים שעוברים מגרסאות Astro מוקדמות יותר נאלצים כעת לכתוב מחדש פלאגינים, אחרת הם מסתכנים בדפים שבורים.

למה השינוי הזה חשוב

המנוע החדש מריץ syntax highlighter מובנה לפני כל פלאגין שסופק על ידי המשתמש, ומקבל רק שלושה שדות קונפיגורציה ברמת ה-top-level. הבחירות הללו מתנגשות עם הדרך שבה רוב פרויקטי Astro מוסיפים פיצ'רים: באמצעות פלאגינים של remark (MDAST) ו-rehype (HAST) שמצפים לרוץ לאחר ה-highlighting, ודרך אובייקט קונפיגורציה גמיש שעובר ישירות למנתח ה-markdown שבבסיס.

ההשלכות מופיעות בכל דף המשלב מתמטיקה בסגנון LaTeX עם תוכן רגיל. מתמטיקה inline ($a+b$) מרונדרת כראוי, אך בלוק display ($$a+b$$) עוטף בתג <pre>, ומציג markup גולמי במקום משוואה מעוצבת. עוגני כותרות (heading anchors) המאפשרים קישורי תוכן עניינים או deep-linking נעלמים, מכיוון שפלאגין יצירת ה-ID רץ לפני מנהל ה-ID המובנה, מה שלא משאיר דבר עבור פלאגין ה-autolink להיאחז בו. מפתחים שניסו לבצע כוונון עדין ל-syntax highlighter של Shiki באמצעות אובייקט shikiConfig יגלו שההגדרה נעלמה ללא עקבות.

התיקונים הטכניים

1. רינדור מתמטיקה לפני ה-highlighting

סיבת השורש היא סדר הפעולות: ה-highlighter של Sätteri "תופס" את הטקסט ראשון ומסווג את בלוק המתמטיקה כקוד רגיל. כדי להחזיר את המתמטיקה למסלול, יש להעביר את העיבוד לשכבת ה-MDAST (עץ התחביר המופשט המייצג את ה-markdown לפני שהוא הופך ל-HTML). החליפו כל פלאגין מתמטיקה ברמת HAST במקביליו ברמת MDAST והריצו אותם לפני שלב ה-highlighter. בפועל, החליפו פלאגינים של remark-math בגרסה שמתחברת לשלב ניתוח ה-markdown, ולאחר מכן אפשרו ל-highlighter לעבוד על צמתי המתמטיקה שכבר עברו המרה.

2. שינוי סדר פלאגיני ה-heading-ID

מזהי כותרות (heading IDs) נוצרים על ידי פלאגין מובנה שמורץ כעת אחרי הפלאגינים של המשתמש. העבירו מחוללי ID או slug מותאמים אישית לראש רשימת הפלאגינים כדי שירוצו ראשונים. רצף טיפוסי שמחזיר את קישורי העוגן נראה כך:

  1. פלאגין slug/ID
  2. פלאגין autolink
  3. כל פלאגין remark אחר

כאשר ה-IDs קיימים מוקדם יותר, פלאגין ה-autolink יכול להצמיד את אלמנטי ה-<a> המצופים, ותוכן העניינים יצביע על הסעיפים הנכונים.

3. הקפדה על סכימת הקונפיגורציה המחמירה של Sätteri

Sätteri מכיר רק בשלושה שדות בהגדרות ה-markdown של Astro. כל דבר אחר, כמו shikiConfig, פשוט נזרק בשקט. כדי לשמור על ערכות נושא מותאמות אישית או שינויי highlighter, העבירו את ההגדרות הללו לרמה המתאימה בהיררכיית הקונפיגורציה של Astro.

מדריך החלפה מהיר

אם אתם מעבירים (porting) מחסנית (stack) markdown קלאסית של Astro, החליפו את פלאגיני ה-remark הישנים ב-feature flags החדשים ש-Sätteri מזהה:

  • 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) – פלאגינים רואים את העץ פעם אחת; הם אינם יכולים לחזור לצמתים (nodes) שנוצרו בשלבים מאוחרים יותר בצינור העיבוד (pipeline).
  • Factory עבור state – צרו אובייקט state חדש עבור כל דף כדי למנוע דליפת נתונים בין דפים.
  • צמתים בלתי ניתנים לשינוי (Immutable nodes) – החזירו צומת חדש כשאתם זקוקים לשינוי; שינוי (mutation) של צומת קיים עלול לשבש שלבי עיבוד עוקבים.
  • ללא root fragments – הכניסו אחים (siblings) באמצעות פונקציות העזר להכנסה (insertion helpers) שסופקו, במקום ליצור צומת fragment ברמת ה-top-level.

כשאתם מתאימים פלאגין קיים, אל תסתמכו על פלט הדוגמה ב-README. רנדרו את ה-HTML של הפלאגין המקורי, העתיקו את ה-markup הזה, והשתמשו בו כנקודת ייחוס עבור הגרסה התואמת ל-Sätteri שלכם.

סיכום

מנוע ה-Sätteri של Astro 7 מביא מהירות אך מחייב שינוי סדר בשרשרת עיבוד ה-markdown: רנדרו מתמטיקה ברמת ה-MDAST, הציבו את תוספי ה-heading-ID בתחילת התהליך, והגבילו את ההגדרות לשלושת השדות המקובלים. עקבו אחר מיפוי ה-feature-flag, הקפידו על כללי ה-single-pass וה-immutable-node, ותשיבו את המתמטיקה, העוגנים (anchors) והעיצוב המותאם אישית (custom theming) שהאתר שלכם תלוי בהם. המאמץ הוא מראש; התמורה היא pipeline של markdown מהיר וצפוי יותר.