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

אם אתם מסתמכים על מתמטיקה בסגנון LaTeX, קישורי כותרות אוטומטיים או תוספי markdown מותאמים אישית, השדרוג עלול להפוך את התוכן שלכם לבלתי קריא ואת הניווט לבלתי שמיש, לכן חשוב לתקן זאת במהירות.

למה השדרוג שבר דברים

Astro מריצה כעת את Sätteri כמעבד ה-Markdown המרכזי שלה. Sätteri משנה את הסדר שבו תוספים (plugins) מיושמים: היא מריצה הדגשת תחביר (syntax highlighting) לפני תוספי ה-HTML-AST (HAST) שאולי הגדרתם. השינוי הזה אומר שלושה דפוסים נפוצים מפסיקים לעבוד:

  • Display math – בלוקים המוקפים ב-$$ … $$ מטופלים כקוד רגיל מכיוון שה-highlighter מופעל ראשון.
  • Heading anchors – תוספים שמייצרים slugs (מזהים ידידותיים ל-URL) ואז יוצרים קישורים אוטומטיים לכותרות הללו כבר לא רואים את ה-IDs, ולכן הקישורים לא נוצרים מעולם.
  • Custom options – כל הגדרה נוספת שהעברתם ישירות למעבד Sätteri תתעלם; Astro מעבירה רק שלושה שדות מוגדרים מראש.

התיקונים המעשיים

1. רנדרו מתמטיקה על ה-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 יכול לעטוף אותה בעוגן המתאים.

3. הציבו הגדרות נוספות ברמה הגבוהה ביותר של אובייקט ה-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 חדש ב-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) בין דפים.
  • Immutable nodes – לעולם אל תשנו צומת (node) במקום; החזירו אובייקט צומת חדש כדי שהמעבד יוכל לעקוב אחר השינויים בצורה נכונה.
  • Insert helpers – השתמשו ב-ctx.insertBefore או ctx.insertAfter כאשר אתם צריכים להוסיף צמתים אחים, במקום לבצע splicing לעץ באופן ידני.

הקפדה על כללים אלו שומרת על יציבות המעבד ומונעת באגים שקשה לעקוב אחריהם.

מה כדאי לעקוב אחריו בהמשך

התיעוד של Astro עדיין מציג את סדר התוספים הישן כברירת מחדל, לכן פרויקטים חדשים עלולים לרשת את ההתנהגות השבורה מבלי כוונה. עקבו אחר גרסאות Astro קרובות לאפשרות של תיקון מובנה שיסדר מחדש את תוסף ה-heading-ID הפנימי. בינתיים, הצעדים לעיל הם הדרך האמינה היחידה לשחזר רינדור מתמטיקה, עוגני כותרות ואפשרויות markdown מותאמות אישית לאחר המעבר ל-Astro 7.

בשורה התחתונה: המעבר למנוע Sätteri של Astro 7 דורש העברת הטיפול במתמטיקה ל-mdastPlugins, הצבת תוסף ה-slug לפני ה-autolinks, והוצאת כל הגדרות ה-markdown הנוספות מתוך אובייקט המעבד; ברגע שיתבצעו שלושת ההתאמות הללו, המשוואות, קישורי הניווט ותכונות ה-markdown המותאמות אישית באתר שלכם יעבדו כפי שעבדו קודם.