Перехід Astro 7 на Rust-орієнтований рушій маркдауну Sätteri перетворив плавне оновлення на кошмар у трьох аспектах для сайтів, що покладаються на математичні формули, якорі заголовків та кастомну конфігурацію. Вбудовані (inline) рівняння все ще працюють, але блоки display-math відображаються як фрагменти коду у вигляді звичайного тексту, ID заголовків зникають, а будь-які додаткові опції, які ви додаєте в конфігурацію Astro, ігноруються без жодних попереджень. Розробникам, які переходять з попередніх версій Astro, тепер доводиться переписувати плагіни або ризикувати поломкою сторінок.

Чому це важливо

Новий рушій запускає вбудований підсвітник синтаксису (syntax highlighter) перед будь-якими користувацькими плагінами та приймає лише три поля конфігурації верхнього рівня. Ці зміни суперечать тому, як більшість проєктів Astro додають функціонал: через плагіни remark (MDAST) та rehype (HAST), які мають запускатися після підсвічування, а також через гнучкий об'єкт конфігурації, який передається безпосередньо в базовий парсер маркдауну.

Наслідки проявляються на будь-якій сторінці, де LaTeX-подібна математика змішана зі звичайним контентом. Вбудована математика ($a+b$) рендериться нормально, але блок display-math ($$a+b$$) огортається в тег <pre>, відображаючи сирий маркдаун замість відформатованого рівняння. Якорі заголовків, які забезпечують посилання у змісті або deep-linking, зникають, оскільки плагін генерації ID запускається перед вбудованим обробником ID, і плагіну autolink просто немає до чого прив'язатися. Розробники, які намагалися налаштувати підсвітник синтаксису Shiki за допомогою об'єкта shikiConfig, виявляють, що це налаштування зникло безслідно.

Технічні виправлення

1. Рендеринг математики перед підсвічуванням

Першопричиною є порядок операцій: підсвітник Sätteri спочатку захоплює текст, класифікуючи блок математики як звичайний код. Щоб повернути математику, перенесіть обробку на рівень MDAST (абстрактне синтаксичне дерево, яке представляє маркдаун до того, як він стане HTML). Замініть будь-які математичні плагіни рівня HAST на їхні еквіваленти MDAST і запускайте їх перед етапом підсвічування. На практиці замініть плагіни remark-math на версію, яка підключається до етапу парсингу маркдауну, а потім дозвольте підсвітнику працювати вже з конвертованими вузлами математики.

2. Зміна порядку плагінів ID заголовків

ID заголовків генеруються вбудованим плагіном, який тепер виконується після користувацьких плагінів. Перемістіть кастомні генератори ID або slug у початок списку плагінів, щоб вони запускалися першими. Типова послідовність, яка відновлює посилання-якорі, виглядає так:

  1. slug/ID plugin
  2. autolink plugin
  3. будь-які інші remark plugins

Завдяки тому, що ID будуть створені на ранньому етапі, плагін autolink зможе додати очікувані елементи <a >, і зміст буде посилатися на правильні розділи.

3. Дотримання суворої схеми конфігурації Sätteri

Sätteri розпізнає лише три поля в конфігурації маркдауну Astro. Усе інше, наприклад shikiConfig, просто ігнорується. Щоб зберегти кастомні теми або налаштування підсвічувача, перенесіть ці параметри на відповідний рівень у ієрархії конфігурації Astro.

Швидкий посібник із заміни

Якщо ви переносите класичний стек маркдауну 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

  • Тільки один прохід – плагіни бачать дерево лише один раз; вони не можуть повернутися до вузлів, створених пізніше в конвеєрі.
  • Фабрика для стану – створюйте новий об'єкт стану для кожної сторінки, щоб уникнути витоку даних між сторінками.
  • Незмінні вузли – повертайте новий вузол, якщо вам потрібно внести зміни; мутація існуючого вузла може порушити наступні етапи обробки.
  • Жодних кореневих фрагментів – вставляйте сусідні елементи за допомогою наданих допоміжних функцій вставки (insertion helpers) замість створення вузла фрагмента верхнього рівня.

Адаптуючи існуючий плагін, не покладайтеся на приклад виводу в README. Відрендерите HTML оригінального плагіна, зафіксуйте цей маркдаун і використовуйте його як еталон для вашої версії, сумісної з Sätteri.

Підсумок

Двигун Sätteri в Astro 7 забезпечує швидкість, але вимагає зміни порядку в ланцюжку обробки markdown: рендеринг математичних формул на рівні MDAST, розміщення плагінів heading-ID на початку та обмеження конфігурації трьома прийнятними полями. Дотримуйтесь мапінгу feature-flag, дотримуйтесь правил single-pass та immutable-node, і ви відновите математичні формули, анкори та кастомне оформлення, від яких залежить ваш сайт. Зусилля потрібні на початковому етапі; результатом стане більш передбачуваний і швидший конвеєр обробки markdown.