A mudança do Astro 7 para o motor de markdown Sätteri, baseado em Rust, transformou uma atualização tranquila em um pesadelo triplo para sites que dependem de matemática, âncoras de cabeçalho e configurações personalizadas. Equações inline ainda funcionam, mas blocos de display-math aparecem como trechos de código em texto puro, os IDs de cabeçalho desaparecem e quaisquer opções extras que você adicione à configuração do Astro são ignoradas silenciosamente. Desenvolvedores que migram de versões anteriores do Astro agora precisam reescrever plugins ou correm o risco de ter páginas quebradas.

Por que a mudança importa

O novo motor executa um syntax highlighter integrado antes de qualquer plugin fornecido pelo usuário e aceita apenas três campos de configuração de nível superior. Essas escolhas conflitam com a maneira como a maioria dos projetos Astro adiciona recursos: por meio de plugins remark (MDAST) e rehype (HAST) que esperam ser executados após o highlighting, e por meio de um objeto de configuração permissivo que é repassado para o parser de markdown subjacente.

As consequências aparecem em qualquer página que misture matemática no estilo LaTeX com conteúdo regular. Matemática inline ($a+b$) renderiza corretamente, mas um bloco de display ($$a+b$$) é envolvido por uma tag <pre>, mostrando o markup bruto em vez de uma equação formatada. As âncoras de cabeçalho que alimentam os links do sumário (table-of-contents) ou deep-linking desaparecem porque o plugin de geração de ID é executado antes do manipulador de ID integrado, não deixando nada para o plugin de autolink se conectar. Desenvolvedores que tentaram ajustar o syntax highlighter Shiki com um objeto shikiConfig descobrem que a configuração desapareceu sem deixar vestígios.

As correções técnicas

1. Renderize a matemática antes do highlighting

A causa raiz é a ordem das operações: o highlighter do Sätteri reivindica o texto primeiro, classificando o bloco de matemática como código simples. Para recuperar a matemática, mude o processamento para a camada MDAST (a árvore de sintaxe abstrata que representa o markdown antes de se tornar HTML). Substitua quaisquer plugins de matemática de nível HAST por seus equivalentes MDAST e execute-os antes da etapa de highlighting. Na prática, troque os plugins remark-math por uma versão que se conecte à etapa de parsing do markdown e, em seguida, deixe o highlighter trabalhar nos nós de matemática já convertidos.

2. Reordene os plugins de ID de cabeçalho

Os IDs de cabeçalho são gerados por um plugin integrado que agora é executado após os plugins do usuário. Mova os geradores de ID ou slug personalizados para o topo da lista de plugins para que sejam executados primeiro. Uma sequência típica que restaura os links de âncora é:

  1. plugin de slug/ID
  2. plugin de autolink
  3. quaisquer outros plugins remark

Com os IDs estabelecidos precocemente, o plugin de autolink pode anexar os elementos <a> esperados, e o sumário apontará para as seções corretas.

3. Respeite o esquema de configuração estrito do Sätteri

O Sätteri reconhece apenas três campos na configuração de markdown do Astro. Qualquer outra coisa, como shikiConfig, é descartada silenciosamente. Para manter temas personalizados ou ajustes de highlighter ativos, realoque essas configurações para o nível apropriado na hierarquia de configuração do Astro.

Guia de substituição rápida

Se você estiver portando uma stack de markdown clássica do Astro, substitua os antigos plugins remark pelas novas flags de recursos que o Sätteri entende:

  • 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

Essas flags habilitam as mesmas capacidades sem exigir o carregamento de um plugin separado.

Regras para manter os plugins compatíveis com o Sätteri

  • Apenas uma única passagem – Os plugins veem a árvore apenas uma vez; eles não podem revisitar nós criados posteriormente no pipeline.
  • Fábrica de estado – Crie um novo objeto de estado para cada página para evitar vazamento de dados entre páginas.
  • Nós imutáveis – Retorne um novo nó quando precisar de uma alteração; mutar um nó existente pode quebrar as etapas de processamento subsequentes.
  • Sem fragmentos de raiz – Insira irmãos por meio dos helpers de inserção fornecidos em vez de criar um nó de fragmento de nível superior.

Ao adaptar um plugin existente, não confie na saída de exemplo do README. Renderize o HTML do plugin original, capture esse markup e use-o como ponto de referência para sua versão compatível com o Sätteri.

Conclusão

O motor Sätteri do Astro 7 traz velocidade, mas força uma reordenação da cadeia de processamento de markdown: renderize a matemática no nível MDAST, posicione os plugins de heading-ID no início e restrinja a configuração aos três campos aceitos. Siga o mapeamento de feature-flags, respeite as regras de passagem única (single-pass) e de nós imutáveis (immutable-node), e você restaurará a matemática, as âncoras e o tema personalizado de que seu site depende. O esforço é inicial; a recompensa é um pipeline de markdown mais rápido e previsível.