Переход Astro 7 на движок Markdown Sätteri на базе Rust превращает блоки математических формул (display-math) в обычный код, удаляет якоря заголовков и отбрасывает пользовательские настройки Markdown — это серьезная проблема для всех, кто обновился и теперь видит сломанные уравнения на своем сайте.

Если вы полагаетесь на математику в стиле LaTeX, автоматические ссылки в заголовках или специализированные плагины Markdown, обновление может сделать ваш контент нечитаемым, а навигацию — нерабочей, поэтому быстрое решение проблемы крайне важно.

Почему обновление все сломало

Теперь Astro использует Sätteri в качестве основного процессора Markdown. Sätteri меняет порядок применения плагинов: он запускает подсветку синтаксиса перед плагинами HTML-AST (HAST), которые вы могли настроить. Этот сдвиг приводит к тому, что три распространенных сценария перестают работать:

  • Математические блоки (display math) — блоки, ограниченные $$ … $$, воспринимаются как обычный код, так как подсветка синтаксиса запускается первой.
  • Якоря заголовков — плагины, которые генерируют слаги (URL-совместимые ID), а затем автоматически создают ссылки на эти заголовки, больше не видят ID, поэтому ссылки не создаются.
  • Пользовательские настройки — любые дополнительные параметры, которые вы передавали напрямую в процессор Sätteri, игнорируются; Astro передает только три предопределенных поля.

Конкретные способы исправления

1. Рендерите математику на уровне markdown-AST (MDAST), а не HTML-AST

Конвейер Markdown в Astro имеет два слота для плагинов:

  • mdastPlugins — запускаются на обработанном дереве Markdown до того, как оно станет HTML.
  • hastPlugins — запускаются на HTML-дереве после конвертации.

Поскольку подсветка синтаксиса запускается перед hastPlugins, математика превращается в блок кода. Перенесите ваш плагин для математики в mdastPlugins.

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

2. Измените порядок плагинов для создания слагов и автоссылок в заголовках

Стандартные конфигурации устанавливают генератор слагов, а затем плагин автоссылок. В Astro встроенный плагин для ID заголовков запускается после вашего списка, из-за чего плагину автоссылок не к чему привязываться. Поместите плагин слагов первым в списке, а затем плагин автоссылок.

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

Теперь каждый заголовок получает ID, и плагин автоссылок может обернуть его соответствующим якорем.

3. Разместите дополнительную конфигурацию на верхнем уровне объекта Astro markdown

Astro передает процессору Sätteri только три конкретных поля. Все, что вы вкладываете внутрь процессора (например, объект shikiConfig), отбрасывается. Перенесите эти дополнительные настройки на верхний уровень конфигурации markdown.

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

Краткий справочник по замене распространенных плагинов remark

Старый плагин remark Новый флаг функций 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) — создавайте новый экземпляр плагина для каждого документа, чтобы избежать утечки состояния между страницами.
  • Неизменяемые узлы (Immutable nodes) — никогда не изменяйте узел на месте; возвращайте новый объект узла, чтобы процессор мог правильно отслеживать изменения.
  • Хелперы вставки (Insert helpers) — используйте ctx.insertBefore или ctx.insertAfter, когда нужно добавить соседние узлы, вместо того чтобы вручную изменять (splice) дерево.

Соблюдение этих правил обеспечивает стабильность процессора и предотвращает трудноотслеживаемые баги.

На что обратить внимание в будущем

В документации Astro все еще указан старый порядок плагинов в качестве стандартного, поэтому новые проекты могут непреднамеренно унаследовать сломанное поведение. Следите за будущими релизами Astro — возможно, там появится встроенное исправление, которое изменит порядок внутреннего плагина heading-ID. А пока вышеуказанные шаги — единственный надежный способ восстановить рендеринг математики, якоря заголовков и пользовательские настройки Markdown после перехода на Astro 7.

Итог: Переход на движок Sätteri в Astro 7 требует переноса обработки математики в mdastPlugins, размещения плагина слагов перед автоссылками и выноса любых дополнительных настроек Markdown из объекта процессора; как только эти три изменения будут внесены, уравнения, навигационные ссылки и пользовательские функции Markdown на вашем сайте снова заработают как прежде.