Rspress 2.0 phát hành: Nâng cấp hoàn toàn mới hướng tới trải nghiệm và AI
Rspress 2.0 phát hành: Nâng cấp hoàn toàn mới hướng tới trải nghiệm và AI
Chúng tôi rất vui mừng thông báo về việc phát hành chính thức Rspress 2.0!
Rspress là một trình tạo trang tĩnh dựa trên Rsbuild, được thiết kế đặc biệt cho các công cụ tài liệu dành cho nhà phát triển. Kể từ khi phát hành chính thức vào năm 2023, Rspress 1.x đã trải qua 144 phiên bản và có 125 nhà đóng góp tham gia phát triển dự án. Ngày càng nhiều nhà phát triển chọn Rspress, nhờ vào hiệu suất biên dịch hiệu quả, định tuyến theo quy ước và xem trước thư viện thành phần để xây dựng các trang tài liệu đẹp và đáng tin cậy.
Dựa trên phản hồi và đề xuất từ cộng đồng, Rspress 2.0 đã tiến xa hơn trong các khía cạnh như độ đẹp của chủ đề, AI-native, trải nghiệm phát triển tài liệu, và sử dụng cùng Rslib.
Tại sao là Rspress 2.0
Rspress 1.x đã giải quyết vấn đề hiệu suất biên dịch của khung tài liệu, nhưng vẫn còn một số vấn đề ảnh hưởng đến trải nghiệm cốt lõi của một công cụ phát triển tài liệu. Phiên bản 2.0 không chỉ tập trung vào hiệu suất biên dịch mà còn chú trọng đến các khía cạnh khác của trải nghiệm trang tài liệu:
- Phong cách chủ đề: Một chủ đề mặc định đẹp hơn và cung cấp nhiều cách tùy chỉnh chủ đề, giải quyết vấn đề thiếu API ổn định trong tùy chỉnh chủ đề của 1.x.
- AI-native: Tài liệu không chỉ phục vụ cho người đọc mà còn cần được Agent hiểu và sử dụng tốt hơn. Rspress hiện đã tích hợp chức năng tạo llms.txt và SSG-MD phát sinh từ SSG, tạo ra nội dung Markdown chất lượng cao để Agent đọc.
- Biên dịch theo yêu cầu, khởi động ngay lập tức: Mặc định kích hoạt lazyCompilation, kết hợp với chức năng preload tài nguyên khi di chuột qua liên kết, chỉ xây dựng các tệp cần thiết khi truy cập vào các định tuyến cụ thể, đảm bảo rằng bất kể quy mô dự án lớn như thế nào, dev cũng có thể khởi động ngay lập tức.
- Tô sáng mã Shiki: Tích hợp Shiki mặc định, hoàn thành tô sáng cú pháp trong quá trình xây dựng, hỗ trợ chuyển đổi chủ đề, mở rộng transformer, chẳng hạn như @rspress/plugin-twoslash, mang lại hiệu ứng hiển thị khối mã phong phú hơn.
- Trải nghiệm phát triển tài liệu: Tối ưu hóa HMR cho các tệp như nav.json, meta.json và thêm json schema để hỗ trợ gợi ý mã trong IDE; mặc định bật chức năng kiểm tra liên kết chết; thêm cú pháp khối mã tệp, hỗ trợ tham chiếu tệp bên ngoài; @rspress/plugin-preview và @rspress/plugin-playground hỗ trợ sử dụng đồng thời, v.v.
- Tích hợp Rslib: Bây giờ bạn có thể chọn Rspress làm công cụ tài liệu khi sử dụng create-rslib để tạo dự án thư viện thành phần, nhanh chóng xây dựng trang tài liệu cho các thành phần.
Tính năng mới 2.0
Chủ đề hoàn toàn mới
Chủ đề mặc định 2.0 đã trải qua một nâng cấp hệ thống, được thiết kế tổng thể bởi nhà thiết kế của đội ngũ @Zovn Wei, với sự cải thiện lớn về hiệu ứng hình ảnh và trải nghiệm đọc, và mỗi thành phần đều có thể được thay thế độc lập, có tính tùy chỉnh cao.
Tùy chỉnh chủ đề
Theo mức độ tùy chỉnh từ thấp đến cao, có bốn cách tùy chỉnh chủ đề: biến CSS, tên lớp BEM, tái xuất ESM, và eject thành phần.- Biến CSS: Chủ đề mới đã tiết lộ nhiều biến CSS hơn, bao gồm màu chủ đề, khối mã, và các kiểu dáng trang chính. Bạn có thể xem trước và điều chỉnh tất cả các biến CSS một cách tương tác trên trang biến CSS, sau khi tìm thấy cấu hình ưng ý, bạn có thể sao chép trực tiếp vào dự án của mình để sử dụng.
- Tên lớp BEM: Các thành phần tích hợp hiện đều sử dụng quy tắc đặt tên BEM. Đây là một lựa chọn rất Old School, nhưng cũng là quyết định được chúng tôi cân nhắc kỹ lưỡng. Người dùng có thể điều chỉnh kiểu dáng một cách chính xác thông qua bộ chọn CSS, cấu trúc HTML trở nên rõ ràng hơn.
- Xuất lại ESM: Nếu các thay đổi trên CSS không đáp ứng được nhu cầu tùy chỉnh, bạn có thể thực hiện tùy chỉnh sâu hơn thông qua JS. Trong theme/index.tsx, bằng cách sử dụng xuất lại ESM, bạn có thể ghi đè bất kỳ thành phần tích hợp nào của Rspress.
- Eject thành phần: Bạn có thể sử dụng lệnh mới rspress eject [component], lệnh này sẽ sao chép mã nguồn của thành phần được chỉ định vào thư mục theme/components/, bạn có thể tự do chỉnh sửa mã này, thậm chí giao cho AI chỉnh sửa, để thực hiện tùy chỉnh sâu.
Thanh điều hướng, thẻ thanh bên
Rspress 2.0 đã triển khai thành phần Tag, bây giờ bạn có thể sử dụng thuộc tính tag trong frontmatter để đánh dấu UI trong thanh bên hoặc thanh điều hướng.
Hỗ trợ đa ngôn ngữ tích hợp
Trong phiên bản 1.x, Rspress chỉ tích hợp văn bản tiếng Anh, nếu sử dụng ngôn ngữ khác như zh, bạn phải cấu hình tất cả các văn bản, điều này khá phức tạp. Bây giờ, chủ đề 2.0 đã tích hợp văn bản dịch cho nhiều ngôn ngữ như zh, en, ja, ko, ru, hệ thống sẽ tự động thực hiện "Tree Shaking" dựa trên cấu hình ngôn ngữ, chỉ đóng gói văn bản và ngôn ngữ mà bạn sử dụng.
Hỗ trợ llms.txt
Rspress hiện đã tích hợp khả năng tạo llms.txt vào core và thực hiện khả năng SSG-MD (Static Site Generation to Markdown, Tạo trang tĩnh sang Markdown).
Trong các khung front-end được render động dựa trên React, thường có vấn đề khó khăn trong việc trích xuất thông tin tĩnh, Rspress cũng phải đối mặt với thách thức tương tự. Rspress cho phép người dùng tăng cường khả năng biểu đạt tài liệu thông qua các đoạn MDX, thành phần React, Hooks và các đặc điểm định tuyến TSX. Nhưng những nội dung động này khi chuyển đổi sang văn bản Markdown sẽ gặp phải các vấn đề sau:
- Việc trực tiếp đưa MDX cho AI sẽ chứa nhiều tiếng ồn cú pháp mã và mất nội dung thành phần React.
- Việc chuyển đổi HTML sang Markdown thường không đạt hiệu quả tốt, chất lượng thông tin khó đảm bảo.
Để giải quyết vấn đề này, Rspress 2.0 đã giới thiệu tính năng SSG-MD. Đây là một chức năng hoàn toàn mới, tương tự như tạo trang tĩnh (SSG), nhưng khác biệt ở chỗ nó sẽ render trang của bạn thành tệp Markdown, thay vì tệp HTML, và tạo ra các tệp llms.txt và llms-full.txt liên quan.
Tô sáng khối mã trong thời gian biên dịch ShikiRspress 2.0 mặc định sử dụng Shiki để làm nổi bật mã. So với giải pháp làm nổi bật thời gian chạy prism của 1.x, Shiki hoàn thành xử lý làm nổi bật tại thời điểm biên dịch.
- Hỗ trợ nhiều kiểu chủ đề, chẳng hạn như có thể chuyển đổi và xem trước các chủ đề Shiki khác nhau một cách tương tác trên trang biến CSS.
- Đồng thời, Shiki cũng cho phép sử dụng transformer tùy chỉnh để mở rộng và làm phong phú thêm việc viết, chẳng hạn như twoslash.
- Nhập ngôn ngữ lập trình theo nhu cầu, không làm tăng chi phí thời gian chạy và kích thước gói.
- Dựa trên cú pháp TextMate để thực hiện làm nổi bật cú pháp chính xác giống như VS Code.
Cải thiện hiệu suất xây dựng
Rspress 2.0 được điều khiển bởi phiên bản xem trước Rsbuild và Rspack 2.0, đồng thời mặc định bật biên dịch theo nhu cầu và bộ nhớ đệm lâu dài.
Biên dịch theo nhu cầu
Mặc định bật dev.lazyCompilation, chỉ khi bạn truy cập vào một trang nào đó, trang đó mới được biên dịch, nâng cao tốc độ khởi động phát triển đáng kể, thậm chí đạt được khởi động lạnh trong mili giây. Rspress cũng thực hiện chiến lược preload cho định tuyến, khi chuột di chuyển qua liên kết, nó sẽ tải trước trang định tuyến mục tiêu, kết hợp với lazyCompilation để tạo ra trải nghiệm phát triển không mất mát.
Bộ nhớ đệm lâu dài
2.0 cũng mặc định bật bộ nhớ đệm lâu dài, tái sử dụng kết quả biên dịch lần trước trong khởi động nóng, nâng cao tốc độ xây dựng từ 30%-60%. Điều này có nghĩa là sau khi chạy lần đầu rspress dev hoặc rspress build, tốc độ khởi động sau đó sẽ được cải thiện rõ rệt.
Trải nghiệm phát triển tài liệu
Mặc định bật kiểm tra liên kết chết
Rspress 2.0 mặc định bật chức năng kiểm tra liên kết chết. Trong quá trình xây dựng, nó sẽ tự động kiểm tra các liên kết không hợp lệ trong tài liệu, giúp bạn phát hiện và sửa chữa kịp thời.
Khối mã tệp
Bạn có thể sử dụng thuộc tính file="./path/to/file" để tham chiếu tệp bên ngoài làm nội dung của khối mã, duy trì mã ví dụ trong các tệp riêng biệt.
preview sử dụng meta linh hoạt hơn
@rspress/plugin-preview hiện tại sử dụng thuộc tính meta, linh hoạt hơn, cũng có thể kết hợp với khối mã tệp.
Rslib & Rspress
Khi sử dụng create-rslib để tạo dự án, bạn hiện có thể chọn công cụ Rspress. Điều này cho phép bạn nhanh chóng xây dựng trang tài liệu đi kèm trong khi phát triển thư viện thành phần, để viết hướng dẫn sử dụng thành phần, hiển thị tham chiếu API, hoặc xem trước hiệu ứng thành phần theo thời gian thực.
Nhiều plugin chính thức Rspress hơn
Rspress 2.0 đã thêm nhiều plugin chính thức:
- @rspress/plugin-algolia: hỗ trợ thay thế tìm kiếm tích hợp của Rspress bằng Algolia DocSearch
- @rspress/plugin-twoslash: thêm gợi ý kiểu cho khối mã TypeScript
- @rspress/plugin-llms: cung cấp khả năng tạo llms.txt cho các dự án không hỗ trợ SSG và SSG-MD
- @rspress/plugin-sitemap: tự động tạo tệp Sitemap, để tối ưu hóa SEO
Thay đổi lớn
Di chuyển từ Rspress 1.x
Nếu bạn là người dùng dự án 1.x, chúng tôi đã chuẩn bị một tài liệu di chuyển chi tiết, giúp bạn nâng cấp từ 1.x lên 2.0. Bạn có thể trực tiếp sử dụng chức năng "sao chép Markdown" trong trang, nhập nó cho agent mã hóa mà bạn thường sử dụng (như Claude Code, v.v.) để hoàn thành việc di chuyển.### Node.js và yêu cầu phiên bản phụ thuộc upstream
Rspress 2.0 yêu cầu phiên bản Node.js 20+, phiên bản React 18+.
Bước tiếp theo
Việc phát hành Rspress 2.0 chỉ là một điểm khởi đầu mới. Sau lần phát hành này, Rspress sẽ tiếp tục phát triển:
- Thúc đẩy tích hợp hệ sinh thái: Kết hợp sâu hơn với Rslib, Rstest, cung cấp trải nghiệm phát triển tích hợp cho các dự án frontend và thư viện thành phần.
- Khám phá tích hợp sâu hơn giữa AI và tài liệu: Như hỏi đáp thông minh, tóm tắt tự động, v.v.; hoàn thiện SSG-MD để nó ổn định và dễ sử dụng hơn.
npm create rspress@latest
