A equipe de código aberto da Meta lançou recentemente o Docusaurus 3.9, uma atualização importante para seu popular gerador de sites estáticos baseado em React.
Sua nova versão, anunciada em 25 de setembro, apresentou um novo recurso significativo: um assistente de pesquisa baseado em IA.
Além dos novos recursos, a atualização também moderniza a tecnologia subjacente, exigindo que os desenvolvedores usem o Node.js 20 e encerrando o suporte para o antigo Node.js 18.
Pesquisa conversacional baseada em IA com DocSearch v4
Para desenvolvedores que mantêm documentação em grande escala, a adição de destaque no Docusaurus 3.9 é o suporte completo para DocSearch v4 da Algolia.
A atualização introduz o AskAI, um recurso que transforma a barra de pesquisa padrão de um site em um assistente de conversação.
Em vez de apenas combinar palavras-chave, a ferramenta fornece respostas sintetizadas, ajudando os usuários. resolva problemas com mais eficiência.
De acordo com a equipe do Docusaurus, o objetivo é “permitir que você adicione um assistente de pesquisa com tecnologia de IA ao seu site Docusaurus que possa responder perguntas com base no que está em sua documentação com uma experiência de conversação.”
Mudar da recuperação de palavras-chave para respostas de conversação marca uma grande evolução na experiência do usuário para documentação técnica.
A implementação desta pesquisa avançada é opt-in, dando às equipes controle sobre a transição. Os mantenedores do projeto podem optar por permanecer no DocSearch v3 ou atualizar gradativamente para desbloquear os novos recursos de IA.
Para aqueles que estão prontos para adotá-lo, Algolia fornece um ponto de entrada acessível. Sua página oficial de preços detalha um nível gratuito de “Build” que inclui 10.000 solicitações de pesquisa por mês, tornando o recurso viável para projetos de código aberto e equipes menores.
Essa integração reflete uma tendência mais ampla do setor de incorporar IA generativa diretamente em plataformas de desenvolvedores para aumentar a produtividade. e reduzir o atrito do usuário.
Modernizando a base: Node.js 20 agora necessário
Em uma mudança que visa melhorar a segurança e o desempenho, o Docusaurus 3.9 aumenta seu requisito mínimo de tempo de execução para o Node.js v20.0, retirando oficialmente o suporte para Node.js 18.
Como o Node.js 18 atingiu seu fim de vida oficial, ele não recebe mais atualizações de segurança, tornando seu uso contínuo uma vulnerabilidade potencial.
A equipe do Docusaurus enquadra essa atualização obrigatória como uma etapa crucial para manter uma plataforma segura e estável.
“Descartando Versões em fim de vida útil do Node.js em lançamentos de versões secundárias são uma prática comum no ecossistema Node.js, que agora endossamos e documentamos oficialmente em nosso processo de lançamento.”
Embora essa decisão seja uma prática recomendada, ela requer ação das equipes de desenvolvimento. Seu impacto mais imediato ocorre nos pipelines de CI/CD e nos ambientes de desenvolvimento local.
Um exemplo prático disso apareceu no GitHub, onde um desenvolvedor registrou um problema observando que os exemplos de documentação oficial para GitHub Actions ainda apontavam para o Node obsoleto 18, exigindo uma atualização para funcionar corretamente.
As equipes precisarão auditar não apenas seus scripts de construção, mas também seus Dockerfiles e gerenciadores de ambiente local para garantir uma transição tranquila e evitar falhas de construção.
Flexibilidade aprimorada para sites de documentação global
Enfrentando um desafio de longa data para sites multilíngues, o Docusaurus 3.9 apresenta melhorias significativas para internacionalização (i18n) system.
Os desenvolvedores agora podem substituir as propriedades `baseUrl` e `url` para cada localidade individualmente usando o novo campo `i18n.localeConfigs[locale]`.
Ele fornece o controle granular necessário para implantações complexas de vários domínios, por exemplo, hospedando documentos em inglês em `docs.example.com` e documentos em francês em `docs.example.fr`, garantindo que todos os metadados e links sejam resolvidos corretamente.
Outras otimizações do i18n incluem um novo sinalizador `translate`, que agora está desabilitado por padrão para sites sem traduções, levando a tempos de construção mais rápidos, evitando leituras desnecessárias do sistema de arquivos.
Além disso, um novo atributo `key` pode ser atribuído aos itens da barra lateral. Adicionar esta chave evita a chave de tradução entra em conflito quando várias categorias compartilham o mesmo rótulo, como’API’, garantindo que cada instância possa ser traduzida exclusivamente com base em seu contexto dentro da estrutura da documentação.
Atualizações principais para diagramas, desempenho e experiência do desenvolvedor
Além dos recursos principais, o Docusaurus 3.9 inclui uma série de outras melhorias valiosas.
Entre elas está o suporte para o algoritmo de layout Mermaid ELK. Mermaid é uma ferramenta popular para criar diagramas a partir de texto, e seu mecanismo de layout ELK fornece recursos de renderização mais sofisticados, o que é especialmente útil para diagramas de arquitetura de sistema grandes ou complexos.
O desempenho também aumenta com uma atualização para o Rspack 1.5, que aproveita novas opções de configuração para acelerar o tempo de compilação do Docusaurus. Compilações mais rápidas se traduzem diretamente em maior produtividade do desenvolvedor, especialmente em projetos grandes.
Outros notáveis as mudanças incluem novos ganchos para lidar com links Markdown quebrados, a capacidade de desativar a renderização de emojis e estabilidade visual aprimorada ao alternar entre modos de cores.
Esses refinamentos coletivos solidificam a posição do Docusaurus como uma plataforma robusta, de alto desempenho e flexível para a construção de sites de documentação modernos.
