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 em 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 colaboradores no desenvolvimento do projeto. Cada vez mais desenvolvedores escolhem o Rspress, aproveitando suas funcionalidades como desempenho de compilação eficiente, 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 aspectos como estética do tema, nativo de IA, experiência de desenvolvimento de documentação, e uso em conjunto com Rslib.
Por que Rspress 2.0
O Rspress 1.x já resolveu os 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 à busca por desempenho de compilação, mas também foca 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 personalizar o tema, 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 recursos integrados de geração de llms.txt e SSG-MD derivados do SSG, gerando conteúdo de renderização 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 função de pré-carregamento de recursos ao passar o mouse sobre os links, construindo apenas os arquivos necessários 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 um esquema JSON para sugestões de código no IDE; verificação de links quebrados ativada por padrão; nova sintaxe de bloco de código de arquivo, suportando referências 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 criar projetos de biblioteca de componentes usando create-rslib, 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, projetada pela designer da equipe @Zovn Wei, com melhorias significativas na estética visual e na experiência de leitura, além de cada componente ser substituível 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 cores de tema, blocos de código, página inicial, entre outros. 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 uso no 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 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 arquivo 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 copia o código-fonte do componente especificado para o diretório theme/components/. Você pode modificar esse código livremente, ou até mesmo entregá-lo para a IA modificar, permitindo uma personalização profunda.
Tag da Barra de Navegação e Lateral
O Rspress 2.0 implementou o componente Tag, permitindo agora o uso da propriedade tag no frontmatter para anotações de 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ê quisesse usar outros idiomas, como zh, era necessário configurar todos os textos, o que era bastante complicado. Agora, o tema 2.0 embute textos traduzidos em várias línguas, como zh, en, ja, ko, ru, etc. O sistema realizará automaticamente o "Tree Shaking" com base na configuração de idioma, empacotando apenas os textos e idiomas que você utilizar.
Suporte a llms.txt
O Rspress agora integra a capacidade de geração de llms.txt ao core e implementou uma nova capacidade de SSG-MD (Geração de Site Estático para Markdown).
Em frameworks de frontend que utilizam renderização dinâmica com React, frequentemente há dificuldades em extrair informações estáticas, e o Rspress enfrenta o mesmo desafio. O Rspress permite que os usuários aumentem 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 MDX diretamente para a IA incluirá muito ruído de sintaxe de código e perderá o conteúdo dos componentes React.
- Converter HTML para Markdown geralmente não produz bons resultados, dificultando a garantia da qualidade da informação.
Para resolver esse problema, o Rspress 2.0 introduziu o recurso SSG-MD. Esta é uma funcionalidade totalmente nova, 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 com ShikiRspress 2.0 usa Shiki para destaque de código por padrão. Em comparação com a solução de destaque em tempo de execução prism da versão 1.x, Shiki realiza o processamento de destaque em tempo de compilação.
- Suporta vários estilos de tema, como na página de variáveis CSS, onde é possível 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 sob demanda, sem aumentar o custo de tempo de execução e o tamanho do pacote.
- Baseado na sintaxe do TextMate, implementa um destaque de sintaxe preciso e consistente com o VS Code.
Melhoria de desempenho na construção
Rspress 2.0 é impulsionado pela versão de pré-visualização do Rsbuild e Rspack 2.0, e por padrão ativa a compilação sob demanda e o cache persistente.
Compilação sob demanda
A compilação dev.lazyCompilation está ativada por padrão, e apenas quando você acessa uma página específica, essa página será compilada, aumentando 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 ao passar o mouse sobre um link, a página de rota alvo será carregada antecipadamente, proporcionando uma experiência de desenvolvimento sem perdas em conjunto com a compilação sob demanda.
Cache persistente
A versão 2.0 também ativa o cache persistente por padrão, reutilizando os resultados da compilação anterior durante a inicialização quente, 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 detecta 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 no 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, agora você pode escolher a ferramenta Rspress. Isso permite que você desenvolva uma biblioteca de componentes enquanto rapidamente monta um site de documentação para escrever instruções de uso dos componentes, exibir referências de API ou visualizar em tempo real os efeitos dos componentes.
Mais plugins oficiais do Rspress
Rspress 2.0 adicionou vários plugins oficiais:
- @rspress/plugin-algolia: suporta substituir a busca embutida do Rspress pelo 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, inserindo-a em seu agente de codificação habitual (como Claude Code, etc.) para completar a migração.### Node.js e os requisitos de versão de 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 front-end 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
