Astro 7 Upgrade Breaks Math, Heading Links and Custom Options – How to Fix It

Przejście Astro 7 na oparty na języku Rust silnik markdown Sätteri powoduje, że bloki display-math zamieniają się w zwykły kod, usuwane są kotwice nagłówków i odrzucane są niestandardowe opcje markdown – to poważny problem dla każdego, kto dokonał aktualizacji i widzi teraz uszkodzone równania na swojej stronie.

Jeśli polegasz na matematyce w stylu LaTeX, automatycznych linkach do nagłówków lub dedykowanych wtyczkach markdown, aktualizacja może sprawić, że Twoje treści staną się nieczytelne, a nawigacja bezużyteczna, dlatego szybkie rozwiązanie tego problemu jest niezbędne.

Dlaczego aktualizacja spowodowała problemy

Astro korzysta teraz z Sätteri jako swojego głównego procesora Markdown. Sätteri zmienia kolejność, w jakiej stosowane są wtyczki: uruchamia podświetlanie składni przed wtyczkami HTML-AST (HAST), które mogłeś skonfigurować. Ta zmiana sprawia, że trzy powszechne wzorce przestają działać:

• Display math – bloki ograniczone przez $$ … $$ są traktowane jako zwykły kod, ponieważ podświetlacz (highlighter) uruchamia się jako pierwszy.
• Kotwice nagłówków – wtyczki generujące slugi (ID przyjazne dla adresów URL), a następnie automatycznie linkujące te nagłówki, nie widzą już identyfikatorów, więc linki nigdy nie zostają utworzone.
• Niestandardowe opcje – wszelkie dodatkowe ustawienia przekazane bezpośrednio do procesora Sätteri są ignorowane; Astro przekazuje tylko trzy zdefiniowane wcześniej pola.

Konkretne rozwiązania

1. Renderuj matematykę na markdown-AST (MDAST) zamiast na HTML-AST

Potok (pipeline) markdown w Astro posiada dwa miejsca na wtyczki:

• mdastPlugins – uruchamiane na sparsowanym drzewie markdown, zanim stanie się ono HTML.
• hastPlugins – uruchamiane na drzewie HTML po konwersji.

Ponieważ podświetlacz uruchamia się przed hastPlugins, matematyka zostaje zamieniona w blok kodu. Przenieś swoją wtyczkę matematyczną do mdastPlugins.

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

2. Zmień kolejność wtyczek slug i autolink dla nagłówków

Standardowe konfiguracje instalują generator slugów, a następnie wtyczkę autolink. W Astro wbudowana wtyczka heading-ID uruchamia się po Twojej liście, nie pozostawiając niczego, do czego wtyczka autolink mogłaby się przypiąć. Umieść wtyczkę slug na początku listy, a następnie wtyczkę autolink.

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

Teraz każdy nagłówek otrzymuje ID, a wtyczka autolink może go owinąć odpowiednią kotwicą.

3. Umieść dodatkową konfigurację na najwyższym poziomie obiektu markdown w Astro

Astro przekazuje do procesora Sätteri tylko trzy konkretne pola. Wszystko, co zagnieździsz wewnątrz procesora (na przykład obiekt shikiConfig), zostaje odrzucone. Przenieś te dodatkowe ustawienia na najwyższy poziom konfiguracji markdown.

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

Szybki przewodnik wymiany dla popularnych wtyczek remark

Stara wtyczka remark	Nowa flaga funkcji 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

Zamień nazwę wtyczki na odpowiadającą jej flagę features.* w konfiguracji Astro.

Dobre praktyki przy przenoszeniu wtyczek do Sätteri

• Wzorzec fabryczny (Factory pattern) – twórz nową instancję wtyczki dla każdego dokumentu, aby uniknąć wycieku stanu między stronami.
• Niemutowalne węzły (Immutable nodes) – nigdy nie mutuj węzła w miejscu; zwróć nowy obiekt węzła, aby procesor mógł poprawnie śledzić zmiany.
• Pomocniki wstawiania (Insert helpers) – używaj ctx.insertBefore lub ctx.insertAfter, gdy musisz dodać węzły rodzeństwa, zamiast ręcznie dzielić (splice) drzewo.

Stosowanie tych zasad zapewnia stabilność procesora i zapobiega trudnym do wykrycia błędom.

Na co zwrócić uwagę w przyszłości

Dokumentacja Astro wciąż podaje starą kolejność wtyczek jako domyślną, więc nowe projekty mogą nieumyślnie przejąć błędne zachowanie. Obserwuj nadchodzące wydania Astro pod kątem możliwej wbudowanej poprawki, która zmieni kolejność wewnętrznej wtyczki heading-ID. W międzyczasie powyższe kroki są jedynym niezawodnym sposobem na przywrócenie renderowania matematyki, kotwic nagłówków i niestandardowych opcji markdown po przejściu na Astro 7.

Podsumowanie: Przejście na silnik Sätteri w Astro 7 wymaga przeniesienia obsługi matematyki do mdastPlugins, umieszczenia wtyczki slug przed autolinkami oraz przeniesienia wszelkich dodatkowych ustawień markdown poza obiekt procesora; po wprowadzeniu tych trzech zmian równania, linki nawigacyjne i niestandardowe funkcje markdown na Twojej stronie będą działać tak jak wcześniej.