Rspress 2.0 lançado: uma nova atualização voltada para experiência e IA
Rspress 2.0 lançado: uma nova atualização voltada para experiência e IA
Estamos felizes em anunciar o lançamento oficial do Rspress 2.0!
Rspress é um gerador de sites estáticos baseado no Rsbuild, projetado como uma ferramenta de documentação para desenvolvedores. Desde seu lançamento oficial em 2023, o Rspress 1.x teve um total de 144 versões e contou com a participação de 125 contribuidores no desenvolvimento do projeto. Cada vez mais desenvolvedores estão escolhendo o Rspress, aproveitando suas funcionalidades como alto desempenho de compilação, roteamento baseado em convenções e visualização de biblioteca de componentes para construir sites de documentação bonitos e confiáveis.
Com base no feedback e nas sugestões da comunidade, o Rspress 2.0 avança em áreas como estética do tema, nativo de IA, experiência de desenvolvimento de documentação, e uso conjunto com Rslib.
Por que Rspress 2.0
O Rspress 1.x já resolveu problemas de desempenho de compilação do framework de sites de documentação, mas ainda existem algumas questões que afetam a experiência central como uma ferramenta de desenvolvimento de documentação. A versão 2.0 não se limita apenas à busca por desempenho de compilação, mas também se concentra em outros aspectos da experiência do site de documentação:
- Estilo do tema: um tema padrão mais bonito, com várias maneiras de personalização, resolvendo a falta de uma API estável para personalização de temas na versão 1.x.
- Nativo de IA: a documentação não apenas serve aos leitores humanos, mas também precisa ser melhor compreendida e utilizada por Agentes. O Rspress agora possui geração de llms.txt embutida e funcionalidades SSG-MD derivadas do SSG, gerando conteúdo de Markdown de alta qualidade para leitura por Agentes.
- Compilação sob demanda, inicialização instantânea: a compilação preguiçosa é ativada por padrão, juntamente com a funcionalidade de pré-carregamento de recursos ao passar o mouse sobre links, construindo arquivos necessários apenas ao acessar rotas específicas, permitindo que, independentemente do tamanho do projeto, o dev possa iniciar instantaneamente.
- Realce de código Shiki: integrado por padrão, o Shiki realiza realce de sintaxe durante a construção, suportando troca de temas e extensões de transformadores, como @rspress/plugin-twoslash, proporcionando uma exibição de blocos de código mais rica.
- Experiência de desenvolvimento de documentação: otimização do HMR de arquivos como nav.json, meta.json, e adição de esquema json para sugestões de código dentro do IDE; verificação de links quebrados ativada por padrão; nova sintaxe de bloco de código de arquivo, suportando referência a arquivos externos; @rspress/plugin-preview e @rspress/plugin-playground suportam uso simultâneo, entre outros.
- Integração com Rslib: agora é possível escolher o Rspress como ferramenta de documentação ao usar create-rslib para criar projetos de bibliotecas de componentes, permitindo a construção rápida de sites de documentação de componentes.
Novos recursos 2.0
Novo tema
O tema padrão 2.0 passou por uma atualização sistemática, projetado pela designer da equipe @Zovn Wei, com melhorias significativas na estética visual e na experiência de leitura, e cada componente pode ser substituído de forma independente, oferecendo alta personalização.
Personalização do tema
De acordo com o nível de personalização, existem quatro maneiras de personalizar o tema: variáveis CSS, nomes de classe BEM, reexportação ESM para sobreposição e ejeção de componentes.- Variáveis CSS: O novo tema expõe mais variáveis CSS, cobrindo estilos de tema, blocos de código, página inicial, etc. Você pode visualizar e ajustar interativamente todas as variáveis CSS na página de variáveis CSS e, após encontrar a configuração desejada, copiá-la diretamente para o projeto.
- Nomes de classe BEM: Os componentes embutidos agora seguem a convenção de nomenclatura BEM. Esta é uma escolha bastante Old School, mas também é uma decisão bem pensada. Os usuários podem ajustar os estilos com precisão através de seletores CSS, tornando a estrutura HTML mais clara.
- Reexportação ESM: Se as modificações no CSS não atenderem às necessidades de personalização, você pode realizar uma personalização mais profunda através do JS. No theme/index.tsx, utilizando a reexportação ESM, é possível substituir qualquer componente embutido do Rspress.
- Ejeção de componentes: Você pode usar o novo comando rspress eject [component], que copiará o código-fonte do componente especificado para o diretório theme/components/, permitindo que você modifique livremente esse código, ou até mesmo o entregue a uma IA para modificações, a fim de alcançar uma personalização profunda.
Tag de barra de navegação e barra lateral
O Rspress 2.0 implementou o componente Tag, agora você pode usar a propriedade tag no frontmatter para marcar a UI na barra lateral ou na barra de navegação.
Suporte multilíngue embutido
Na versão 1.x, o Rspress apenas incluía texto em inglês. Se você usasse outros idiomas, como zh, era necessário configurar todos os textos, o que era bastante complicado. Agora, o tema 2.0 inclui textos traduzidos em várias línguas, como zh, en, ja, ko, ru, etc. O sistema fará "Tree Shaking" automaticamente com base na configuração de idioma, empacotando apenas os textos e idiomas que você utiliza.
Suporte a llms.txt
O Rspress agora integrou a capacidade de geração de llms.txt ao core e implementou uma nova capacidade SSG-MD (Geração de Site Estático para Markdown).
Em frameworks de front-end que renderizam dinamicamente com React, frequentemente há problemas em extrair informações estáticas. O Rspress também enfrenta esse desafio. O Rspress permite que os usuários melhorem a expressividade dos documentos através de fragmentos MDX, componentes React, Hooks e rotas TSX. No entanto, esses conteúdos dinâmicos enfrentam os seguintes problemas ao serem convertidos em texto Markdown:
- Fornecer diretamente o MDX para a IA incluirá muito ruído de sintaxe de código e perderá o conteúdo dos componentes React.
- Converter HTML para Markdown muitas vezes não produz bons resultados, e a qualidade da informação é difícil de garantir.
Para resolver esse problema, o Rspress 2.0 introduziu o recurso SSG-MD. Esta é uma nova funcionalidade que é semelhante à geração de site estático (SSG), mas a diferença é que ela renderiza suas páginas como arquivos Markdown, em vez de arquivos HTML, e gera arquivos relacionados llms.txt e llms-full.txt.
Destaque de código em blocos de código com ShikiRspress 2.0 usa Shiki por padrão para realce de código. Em comparação com a solução de realce em tempo de execução prism 1.x, Shiki realiza o processamento de realce em tempo de compilação.
- Suporta vários estilos de tema, como na página de variáveis CSS, onde você pode alternar e visualizar interativamente diferentes temas do Shiki.
- Ao mesmo tempo, o Shiki também permite o uso de transformers personalizados para enriquecer a escrita, como twoslash, etc.
- Importa linguagens de programação conforme necessário, sem aumentar a sobrecarga em tempo de execução e o tamanho do pacote.
- Baseado na sintaxe do TextMate, implementa um realce de sintaxe preciso consistente com o VS Code.
Melhoria de desempenho na construção
Rspress 2.0 é impulsionado pela versão prévia do Rsbuild e Rspack 2.0, e por padrão, a compilação sob demanda e o cache persistente estão ativados.
Compilação sob demanda
A compilação dev.lazyCompilation está ativada por padrão, e a página só será compilada quando você acessá-la, melhorando significativamente a velocidade de inicialização do desenvolvimento, até mesmo alcançando inicializações a nível de milissegundos. O Rspress também implementou uma estratégia de pré-carregamento de rotas, onde a página de rota de destino será pré-carregada quando o mouse estiver sobre o link, proporcionando uma experiência de desenvolvimento sem perdas em conjunto com a lazyCompilation.
Cache persistente
A versão 2.0 também ativa o cache persistente por padrão, reutilizando os resultados da compilação anterior em inicializações quentes, aumentando a velocidade de construção em 30%-60%. Isso significa que após a primeira execução de rspress dev ou rspress build, a velocidade de inicialização subsequente será significativamente melhorada.
Experiência de desenvolvimento de documentação
Verificação de links quebrados ativada por padrão
Rspress 2.0 ativa a verificação de links quebrados por padrão. Durante o processo de construção, ele detectará automaticamente links inválidos na documentação, ajudando você a identificá-los e corrigi-los a tempo.
Blocos de código de arquivo
Você pode usar o atributo file="./path/to/file" para referenciar arquivos externos como conteúdo de blocos de código, mantendo o código de exemplo em arquivos separados.
Uso de meta mais flexível em preview
@rspress/plugin-preview agora usa o atributo meta, tornando-o mais flexível, e também pode ser combinado com blocos de código de arquivo.
Rslib & Rspress
Ao usar create-rslib para criar um projeto, você agora pode escolher a ferramenta Rspress. Isso permite que você construa rapidamente um site de documentação para escrever instruções de uso de componentes, exibir referências de API ou visualizar em tempo real os efeitos dos componentes enquanto desenvolve uma biblioteca de componentes.
Mais plugins oficiais do Rspress
Rspress 2.0 adicionou vários plugins oficiais:
- @rspress/plugin-algolia: suporta substituir a busca embutida do Rspress pela Algolia DocSearch
- @rspress/plugin-twoslash: adiciona dicas de tipo para blocos de código TypeScript
- @rspress/plugin-llms: fornece capacidade de geração de llms.txt para projetos que não suportam SSG e SSG-MD
- @rspress/plugin-sitemap: gera automaticamente arquivos Sitemap para otimizar SEO
Mudanças significativas
Migração do Rspress 1.x
Se você é um usuário de projetos 1.x, preparamos um documento de migração detalhado para ajudá-lo a atualizar do 1.x para o 2.0. Você pode usar diretamente a função "Copiar Markdown" na página para inserir em seu agente de codificação habitual (como Claude Code, etc.) para concluir a migração.### Node.js e os requisitos de versão das dependências upstream
Rspress 2.0 requer Node.js versão 20+, React versão 18+.
Próximos passos
O lançamento do Rspress 2.0 é apenas um novo ponto de partida. Após este lançamento, o Rspress continuará a iterar:
- Avançar na integração do ecossistema: combinar mais profundamente com Rslib e Rstest, oferecendo uma experiência de desenvolvimento integrada para projetos de frontend e bibliotecas de componentes.
- Explorar uma integração mais profunda de AI com documentos: como perguntas e respostas inteligentes, resumos automáticos, etc.; aprimorar o SSG-MD para torná-lo estável e mais fácil de usar.
npm create rspress@latest
