A mudança do Astro 7 para o motor de markdown Sätteri, baseado em Rust, está transformando blocos de matemática exibida (display-math) em código simples, removendo âncoras de cabeçalho e descartando opções personalizadas de markdown – um problema para quem atualizou e agora vê equações quebradas em seu site.

Se você depende de matemática no estilo LaTeX, links automáticos de cabeçalho ou plugins de markdown sob medida, a atualização pode tornar seu conteúdo ilegível e sua navegação inutilizável, portanto, corrigi-la rapidamente é essencial.

Por que a atualização quebrou as coisas

O Astro agora executa o Sätteri como seu processador de Markdown principal. O Sätteri altera a ordem em que os plugins são aplicados: ele executa o realce de sintaxe (syntax highlighting) antes dos plugins HTML-AST (HAST) que você possa ter configurado. Essa mudança significa que três padrões comuns param de funcionar:

  • Matemática exibida (Display math) – blocos delimitados por $$ … $$ são tratados como código comum porque o realçador (highlighter) é executado primeiro.
  • Âncoras de cabeçalho – plugins que geram slugs (IDs amigáveis para URL) e depois criam links automáticos para esses cabeçalhos não conseguem mais ver os IDs, portanto, os links nunca são criados.
  • Opções personalizadas – quaisquer configurações extras que você passou diretamente para o processador Sätteri são ignoradas; o Astro encaminha apenas três campos predefinidos.

As correções concretas

1. Renderize a matemática no markdown-AST (MDAST) em vez do HTML-AST

O pipeline de markdown do Astro possui dois slots de plugins:

  • mdastPlugins – executados na árvore de markdown analisada antes de se tornar HTML.
  • hastPlugins – executados na árvore HTML após a conversão.

Como o realçador é executado antes de hastPlugins, a matemática é transformada em um bloco de código. Mova seu plugin de matemática para mdastPlugins.

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

Configurações padrão instalam um gerador de slug seguido por um plugin de autolink. No Astro, o plugin de ID de cabeçalho integrado é executado depois da sua lista, não deixando nada para o plugin de autolink anexar. Coloque o plugin de slug primeiro na lista e, em seguida, o plugin de autolink.

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

Agora cada cabeçalho recebe um ID e o plugin de autolink pode envolvê-lo com a âncora apropriada.

3. Coloque a configuração extra no nível superior do objeto markdown do Astro

O Astro encaminha apenas três campos específicos para o processador Sätteri. Qualquer coisa que você aninhe dentro do processador (por exemplo, um objeto shikiConfig) é descartada. Mova essas configurações extras para o nível superior da configuração markdown.

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

Guia de substituição rápida para plugins remark comuns

Plugin remark antigo Nova flag de recurso do 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

Substitua o nome do plugin pela flag features.* correspondente em sua configuração do Astro.

Melhores práticas ao portar plugins para o Sätteri

  • Padrão Factory – crie uma nova instância de plugin por documento para evitar o vazamento de estado entre as páginas.
  • Nós imutáveis – nunca mude um nó no local; retorne um novo objeto de nó para que o processador possa rastrear as alterações corretamente.
  • Helpers de inserção – use ctx.insertBefore ou ctx.insertAfter quando precisar adicionar nós irmãos, em vez de fazer o splice da árvore manualmente.

Seguir essas regras mantém o processador estável e evita bugs difíceis de rastrear.

O que observar a seguir

A documentação do Astro ainda lista a antiga ordem de plugins como padrão, portanto, novos projetos podem herdar o comportamento problemático sem intenção. Fique atento aos próximos lançamentos do Astro para uma possível correção integrada que reordene o plugin interno de ID de cabeçalho. Enquanto isso, as etapas acima são a única maneira confiável de restaurar a renderização de matemática, âncoras de cabeçalho e opções personalizadas de markdown após a mudança para o Astro 7.

Resumo: A mudança para o motor Sätteri do Astro 7 exige mover o tratamento de matemática para mdastPlugins, colocar o plugin de slug antes dos autolinks e retirar quaisquer configurações extras de markdown do objeto do processador; uma vez feitos esses três ajustes, as equações, os links de navegação e os recursos de markdown personalizados do seu site funcionarão como antes.