Rspress 2.0 发布：面向体验与 AI 的全新升级
我们很高兴地宣布 Rspress 2.0 的正式发布！ Rspress 是基于 Rsbuild 的静态站点生成器，专为开发者打造的文档站工具。自 2023 年正式发布以来，Rspress 1.x 累计迭代 144 个版本，共有 125 位贡献者 参与项目开发。越来越多的开发者选择 Rspress，借助其高效的编译性能、约定式路由和组件库预览等功能，构建了可靠的文档站点。 根据社区的反馈和建议，Rspress 2.0 在 主题美观度、人工智能原生、文档开发体验、与 Rslib 一起使用 等方面进行了更深入的研究。 Rspress 1.x 已经解决了文档站框架编译性能的问题，但仍然存在一些问题影响着作为文档开发工具的核心体验。2.0 版本将不仅仅针对编译性能的追求，也侧重于文档站体验的其他方面： 主题风格：一套更美观的默认主题，并提供了多种自定义主题方式，解决了 1.x 在主题定制上缺乏稳定 API 的问题； AI-native：文档不仅服务于人类读者，也需要被 Agent 更好地理解和使用。Rspress 现在内置了 llms.txt 生成并从 SSG 衍生出的 SSG-MD 功能，生成高质量的 Markdown 渲染内容供 Agent 读取； 双击编译，瞬间启动：默认启用 lazyCompilation，配合链接悬停时对资源的预加载功能，仅在访问特定路由时构建所需文件，无论实现项目规模大小，dev 也可瞬间启动； Shiki 代码高亮：默认集成 Shiki，在构建时完成语法高亮，支持主题切换、变压器扩展，比如 @rspress/plugin-twoslash，带来更丰富的代码块展示效果； 文档开发体验：优化 Rslib 集成：现在可以在使用 这是一次对现有架构的全面升级，下面将介绍 Rspress 2.0 及其 全新主题、高质量 llms.txt 生成、集成 Shiki、后续编译等重要功能。 2.0 默认主题令人期待的一次系统性升级，它由团队设计师 @Zovn Wei 整体设计，在视觉效果和阅读体验上都有较轻的提升，并且每个组件需要独立替换，拥有非常多的可定制性。 主题定制 按照定制化程度从低到高，有 CSS 变量、BEM 类名、ESM 重导出覆盖、组件弹出四种自定义主题[11]方式。 CSS 指标：新主题涉及了更多 CSS 指标，覆盖主题颜色、代码块、首页等样式。您可以在 CSS 指标[12] 页面进行预览并调整所有 CSS 指标，找到满意的配置后直接复制到项目中使用。 BEM 类名：内置组件现在均采用 BEM 命名规范。这是十分之一 Old School 的选择，但也是我们深思熟虑的决定。用户可以通过 CSS 选择器精准调整样式，HTML 结构更加清晰；同时与 Rspress 用户自身使用的 CSS 框架解耦合，用户可以任意选择 CSS 框架（Tailwind [14]、Less [15]、Sass [16] 等），比如使用 Tailwind V4 或 V3 而不用担心版本，也不用担心与 Rspress 内置 CSS 产生冲突。 ESM 重导出覆盖：如果 CSS 上的修改无法满足定制需求，可以通过 JS 进行更深度的定制。在 修改组件弹出：你可以使用全新的 `rspress pop [组件]` 命令，这个命令将指定的组件源代码复制到 导航栏、侧边栏标签 Rspress 2.0 实现了 Tag 组件[19]，现在可以使用 frontmatter 中的标签属性，在侧边栏或导航栏进行 UI 标注。 内置多语言支持 在 1.x 版本中，Rspress 仅内置了中文，如果使用其他语言如 zh，必须对所有的文本都进行配置，使用起来更繁琐。现在 2.0 主题内置了 zh、en、ja、ko、ru 等多种语言的翻译文本，系统会根据语言配置自动进行“Tree Shaking”，仅限你使用到的文本及语言，未内置的语言会兜底到 en 文本。您也可以通过 `i18nSource` 配置项扩展或覆盖翻译文本。 Rspress 未来会支持更多内置语言，如果你有兴趣，请参考 这位贡献者的 Pull Request [21]。 Rspress 现在将 llms.txt [22] 生成能力集成到 core 中，并实现了全新的 SSG-MD（Static Site Generation to Markdown，静态站点 Markdown 生成）能力。 在基于 React 动态渲染的前端框架中，往往存在静态信息无法提取的问题，Rspress 也面临同样的挑战。Rspress 用户通过 MDX 片段[23]、React 组件、Hooks 以及 TSX 路由等动态特性来增强表现力。但这些动态转换在 Markdown 文本内容时会面临以下问题： 直接将 MDX 输入给 AI 会包含大量代码噪音，并丢失 React 组件内容； 将 HTML 转为 Markdown 往往效果不佳，信息质量难以保证。 为了解决这个问题，Rspress 2.0 引入了 SSG-MD [24] 特性。这是一个全新的功能，它类似于 静态站点生成（SSG）[25]，但不同的地方相当于你的页面渲染为 Markdown，而不是文件 HTML 文件，并生成 llms.txt [26] 及 llms-full.txt 相关文件。 相比于将 HTML 转化为 Markdown 等传统方式，SSG-MD 在渲染期间拥有更优质的信息源，比如 React 虚拟 DOM，从而保证更高的静态信息质量和灵活性。 启用方式非常简单： 构建后将生成如下结构： 若想定制自定义组件的渲染内容，可通过环境变量控制： 这样既保证了文档的交互体验，也能帮助 AI 理解组件的语义信息。 参见 SSG-MD 使用指南[27] Rspress 2.0 默认使用 Shiki [28] 进行代码高亮。相比 1.x 的 prism 运行时高亮方案，Shiki 在编译时完成高亮处理。 支持多种主题样式，比如在 CSS 变量[29] 页面可以交互式切换和预览不同的 Shiki 主题。 同时 Shiki 也允许使用自定义的 变压器[30] 进行扩展来丰富的写作，例如 twoslash 等。 引入编程语言，不增加运行时间和包体积。 基于 TextMate 语法实现与 VS Code 一致的准确语法高亮。 下面是一些 Shiki Transformer 的视觉，仔细感受 Shiki 带来的文档创意： 使用 @rspress/plugin-twoslash [31] 使用 transformerNotationFocus [32] 参见 代码块[33] Rspress 2.0 底层由 Rsbuild 和 Rspack 2.0 预览版本驱动，同时默认开启了后续编译[34] 和 持久化存储[35]。 编译 默认开启 dev.lazyCompilation [36]，只有当你访问某些页面时，该页面才会被编译，大幅提升了开发速度启动，甚至实现了数十级的冷启动。Rspress 同时实现了路由的预加载策略，当鼠标暂停在链接上时会预先加载目标路由页面，搭配 lazyCompilation 实现稀疏的开发体验。 持久化存储 2.0 默认同时开启了 持久化服务器[37]，在热启动中复用上次编译的结果，提升了 30%-60%的构建速度。这意味着在首次运行 默认开启死链检查 Rspress 2.0 默认开启死链检查功能。在构建过程中，会自动检测文档中的无效链接，帮助你及时发现和修复。 参见 链接[38] 文件代码块 您可以使用 file="./path/to/file" 属性来引用外部文件作为代码块的内容，将示例代码放在单独的文件中维护中。 请参阅 文件代码块[39] 预览 更灵活的元用法 @rspress/plugin-preview [40] 现在基于元属性使用，更加灵活，也可以殴打文件代码块。 下面是一个使用 iframe 预览代码块的示例： 它将会渲染为： 并且 @rspress/plugin-playground [41] 现在支持和 plugin-preview 一起使用，通过 meta 属性切换即可，例如 支持 HMR 的一些配置文件 基于 Rsbuild 重新设计的 虚拟模块插件[42]，现在支持 在使用 执行 模版中内置了 rsbuild-plugin-workspace-dev [43] 插件，可在启动 Rspress 开发服务器的同时自动运行 Rslib 的 watch 命令。 直接运行 Rspress 2.0 新增了多个官方插件： @rspress/plugin-algolia：支持替换 Rspress 的内置搜索为 Algolia DocSearch （感谢 @algolia 团队的帮助）； @rspress/plugin-twoslash：为 TypeScript 代码块添加类型提示； @rspress/plugin-llms：为不支持 SSG 和 SSG-MD 的项目提供 llms.txt 生成能力； @rspress/plugin-sitemap：自动生成 Sitemap 文件，用于优化 SEO。 如果您是 1.x 项目的用户，我们准备了一份升级的迁移文档，帮助您从 1.x 升级到 2.0。 你可以直接使用 Pages 中的“复制 Markdown”功能，将其输入给你常用的编码代理（如 Claude Code 等）来完成迁移。 请参考 迁移指南[51]。 我们注意到很大一部分 1.x 用户为了使用 Shiki、组件库预览功能和自定义评论/rehype 插件，而主动关闭 为了换取更好的扩展性和可维护性，我们决定在 Markdown/MDX 编译流程中不再使用 Rust 版本的 MDX 解析器（ Rspress 2.0 要求 Node.js 版本 20+，React 版本 18+。 Rspress 将 如果你开发了 Rspress 插件，那么该插件的 peerDependency 从 Rspress 2.0 的发布只是一个新的起点。本次发布后，Rspress 将持续迭代： 推进生态集成：与 Rslib、Rstest 更深度地结合，提供接入组件项目和库项目的标准化开发体验； 探索 AI 与文档更复杂的集成：如智能问答、自动摘要等；完善 SSG-MD 决策并更加自动化。 感谢所有为 Rspress 做出贡献的开发者和用户！如果您在使用过程中遇到问题或有任何建议，欢迎在 GitHub Issues [52] 中反馈。 立即使用或升级到 Rspress 2.0，体验全新的文档开发之旅！ 博客原文链接：https://rspress.rs/zh/blog/rspress-v2 参考资料 [1] Rsbuild：https://rsbuild.rs/ [2] 自定义主题： https://v2.rspress.rs/zh/guide/basic/custom-theme [3] llms.txt： https://llmstxt.org/ [4] SSG-MD： https://v2.rspress.rs/zh/guide/basic/ssg-md [5] 懒加载编译： https://rspack.rs/guide/features/lazy-compilation [6] @rspress/plugin-twoslash: https://v2.rspress.rs/zh/plugin/official-plugins/twoslash [7] json 模式： https://v2.rspress.rs/zh/guide/basic/auto-nav-sidebar #json -schema-type 提示 [8] @rspress/plugin-preview: https://v2.rspress.rs/zh/plugin/official-plugins/preview [9] @rspress/plugin-playground： https://rspress.rs/plugin/official-plugins/playground [10] @Zovn 魏： https://x.com/wei_zhong41532 [11] 自定义主题： https://v2.rspress.rs/zh/guide/basic/custom-theme [12] CSS 变量： https://v2.rspress.rs/zh/ui/vars [13] BEM 命名规范： https://getbem.com/ [14] Tailwind： https://tailwindcss.com/ [15] Less： https://lesscss.org/ [16] Sass： https ://sass-lang.com/ [17] ESM 重新导出： https://v2.rspress.rs/zh/guide/basic/custom-theme #reexport [18] [19] 标签组件： https://v2.rspress.rs/zh/ui/layout-components/tag [20] [21] 贡献者的 Pull 请求： https://github.com/web-infra-dev/rspress/pull/2827 [22] llms.txt： https://llmstxt.org/ [23] MDX 片段： https://v2.rspress.rs/zh/guide/use-mdx/components [24] SSG-MD： https://v2.rspress.rs/zh/guide/basic/ssg-md [25] 静态站点生成（SSG）： https://v2.rspress.rs/zh/guide/basic/ssg [26] llms.txt： https://llmstxt.org/ [27] SSG-MD 使用指南： https://v2.rspress.rs/zh/guide/basic/ssg-md [28] Shiki： https://shiki.style/ [29] CSS 变量： https://v2.rspress.rs/zh/ui/vars [30] 变形金刚： https://shiki.style/guide/transformers [31] @rspress/plugin-twoslash: https://v2.rspress.rs/zh/plugin/official-plugins/twoslash [32] transformerNotationFocus： https://v2.rspress.rs/zh/guide/use-mdx/code-blocks #transformernotationfocus [33] 代码块： https: //v2.rspress.rs/zh/guide/use-mdx/code-blocks #shiki -transformers [34] 编译： https://rspack.rs/zh/guide/features/lazy-compilation [35] 持久化服务器： https://rsbuild.rs/zh/config/performance/build-cache [36] dev.lazyCompilation： https://rsbuild.rs/zh/config/dev/lazy-compilation [37] 持久化服务器： https://rsbuild.rs/zh/config/performance/build-cache [38] 链接： https ://v2.rspress.rs/zh/guide/use-mdx/link [39] 文件代码块： https: //v2.rspress.rs/zh/guide/use-mdx/code-blocks #file -code-block [40] @rspress/plugin-preview: https://v2.rspress.rs/zh/plugin/official-plugins/preview [41] @rspress/plugin-playground: https://v2.rspress.rs/zh/plugin/official-plugins/playground [42] 虚拟插件模块： https://github.com/rstackjs/rsbuild-plugin-virtual-module [43] rsbuild-plugin-workspace-dev： https://github.com/rstackjs/rsbuild-plugin-workspace-dev [44] @rspress/plugin-algolia： https://v2.rspress.rs/zh/plugin/official-plugins/algolia [45] Algolia DocSearch： https://docsearch.algolia.com/ [46] @algolia： https://x.com/algolia [47] @rspress/plugin-twoslash： https://v2.rspress.rs/zh/plugin/official-plugins/twoslash [48] @rspress/plugin-llms： https://v2.rspress.rs/zh/plugin/official-plugins/llms [49] @rspress/plugin-sitemap： https://v2.rspress.rs/zh/plugin/official-plugins/sitemap [50] 网站地图： https://www.sitemaps.org [51] 迁移指南： https://v2.rspress.rs/zh/guide/migration/rspress-1-x [52] GitHub Issues： https://github.com/web-infra-dev/rspress/issues为什么是 Rspress 2.0
_nav.json、_meta.json 文件的 HMR 等并新增 json schema 用于 IDE 内的代码提示；默认开启死链检查功能；新增文件代码块语法，支持外部引用文件；@rspress/plugin-preview 和 @rspress/plugin-playground 支持同时使用等；create-rslib 创建组件库项目时，选择 Rspress 作为文档工具，快速构建组件库项目站点。
2.0 新特性
全新主题
:root { /* 自定义主题色 */ --rp-c-brand: #3451b2; --rp-c-brand-dark: #2e4599; /* 自定义代码块样式 */ --rp-code-block-bg: #1e1e1e;}/* BEM 命名规范 */.rp-[component-name]__[element-name]--[modifier-name] {}/* 根据 BEM 类名轻松覆盖组件样式 */.rp-nav__title { height: 32px;}.rp-nav-menu__item--active { color: purple;}theme/index.tsx 中使用 ESM 重导出[17]，可以覆盖任意一个 Rspress 的内置组件。
theme/components/ 目录下，你可以自由这些代码，甚至直接替换 AI，来实现深度定制。# 将 DocFooter 组件导出到 theme 目录rspress eject DocFooter---tag: new, experimental # 会在 H1 和 Sidebar 进行显示---import { Tag } from '@rspress/core/theme';# Tag## Common tags <Tag tag="new" /> {/* 会在右侧 outline 进行显示 */}
llms.txt 支持
import { defineConfig } from '@rspress/core';export default defineConfig({ llms: true,});
Shiki 编译时代码块高亮
const hi = 'Hello';const msg = `${hi}, world`;// ^?console.log('Not focused');console.log('Focused'); // [!code focus]console.log('Not focused');构建性能提升
rspress dev 或 rspress build 之后，后续启动速度都会明显提升。文档开发体验
import { defineConfig } from '@rspress/core';export default defineConfig({ markdown: { link: { checkDeadLinks: true, // 默认开启，可通过 false 关闭 }, },});
```ts file="./_demo.ts"``````tsx file="<root>/src/components/Button.tsx"``````tsx preview="iframe-follow" file="./_demo.ts"```
```tsx playgroundi18n.json、_nav.json、_meta.json文件代码块以及 @rspress/plugin-preview 中 iframe 相关的 HMR。修改这些配置文件后，页面会自动热更新，无需手动刷新。Rslib 和 Rspress
create-rslib 项目项目时，您现在可以选择 Rspress 工具。这让您能够在开发组件库的同时，快速搭建搭建的文档站点，用于编写创建组件的使用说明、展示 API 参考，或实时预览组件效果。npm create rslib@latest 并选中 Rspress，会生成下方的文件结构：├── docs│ └── index.mdx├── src│ └── Button.tsx├── package.json├── tsconfig.json├── rslib.config.ts└── rspress.config.tsnpm run doc 启动 Rspress 的开发服务器对 Rslib 组件库进行预览：{ "scripts": { "dev": "rslib build --watch", "doc": "rspress dev" // 执行该命令 }}更多 Rspress 官方插件
其他重大变化
从 Rspress 1.x 迁移
删除 mdxRs 配置
mdxRs，并且在开启循环编译和持久化缓存后，即使使用 JS 版本的 mdx 解析器，性能优化效果已经非常显着。@rspress/mdx-rs）。这使得 Rspress 能够更好地集成 Shiki 等 JavaScript 生态的工具。Node.js 与下游依赖版本要求
包名及导入路径变更
rspress、、、@rspress/runtime都 整合进了 中，项目@rspress/shared和 插件现在只需安装一个包即可。@rspress/theme-default@rspress/core@rspress/core{ "dependencies": {- "rspress": "1.x"- "@rspress/shared": "1.x"+ "@rspress/core": "^2.0.0" }}- import { defineConfig } from 'rspress/config';+ import { defineConfig } from '@rspress/core';- import { useDark } from 'rspress/runtime'- import { PackageManagerTabs } from 'rspress/theme';+ import { useDark } from '@rspress/core/runtime'+ import { PackageManagerTabs } from '@rspress/core/theme';rspress 更改为 @rspress/core：{ "peerDependencies": { "@rspress/core": "^2.0.0" }}下一步
npm create rspress@latestrspress eject [component]: https://v2.rspress.rs/zh/api/commands #rspress -ejecti18nSource： https://v2.rspress.rs/zh/api/config/config-basic #i18nsource
