Rspress 2.0 Paglabas: Isang Bagong Pag-upgrade na Nakatuon sa Karanasan at AI

Ikinalulugod naming ipahayag ang opisyal na paglabas ng Rspress 2.0!

Ang Rspress ay isang static site generator na batay sa Rsbuild, na dinisenyo bilang isang dokumentasyon na tool para sa mga developer. Mula nang opisyal na ilabas ito noong 2023, ang Rspress 1.x ay nakapagtala ng 144 na bersyon at mayroong 125 na kontribyutor na lumahok sa pagbuo ng proyekto. Mas maraming developer ang pumipili sa Rspress, gamit ang mga tampok nito tulad ng mabilis na pag-compile, convention-based routing, at component library preview upang bumuo ng maganda at maaasahang mga dokumentasyon na site.

Batay sa feedback at mungkahi mula sa komunidad, ang Rspress 2.0 ay higit pang umunlad sa mga aspeto ng kagandahan ng tema, AI-native, karanasan sa pagbuo ng dokumentasyon, at paggamit kasama ang Rslib.

Bakit Rspress 2.0

Ang Rspress 1.x ay nalutas na ang mga isyu sa pag-compile ng framework ng dokumentasyon, ngunit may ilang mga problema pa ring nakakaapekto sa pangunahing karanasan bilang isang tool sa pagbuo ng dokumentasyon. Ang bersyon 2.0 ay hindi lamang nakatuon sa pagbuo ng pagganap, kundi pati na rin sa iba pang aspeto ng karanasan sa dokumentasyon:

• Tema ng Estilo: Isang mas maganda at default na tema, at nagbigay ng iba't ibang paraan ng pag-customize ng tema, na nalutas ang kakulangan ng matatag na API sa pag-customize ng tema sa 1.x.
• AI-native: Ang dokumentasyon ay hindi lamang para sa mga tao kundi kailangan ding mas maunawaan at magamit ng mga Agent. Ngayon, ang Rspress ay may kasamang llms.txt generation at SSG-MD na nagmula sa SSG, na bumubuo ng mataas na kalidad na Markdown na nilalaman para sa mga Agent na basahin.
• On-demand na pag-compile, instant na pagsisimula: Default na pinagana ang lazyCompilation, kasama ang preload na tampok para sa mga resource kapag nag-hover sa link, na bumubuo lamang ng kinakailangang mga file kapag bumibisita sa tiyak na ruta, na nagbibigay-daan sa instant na pagsisimula kahit gaano kalaki ang sukat ng proyekto.
• Shiki code highlighting: Default na isinama ang Shiki, na kumpletong syntax highlighting sa oras ng pagbuo, sumusuporta sa pagbabago ng tema, at mga extension ng transformer, tulad ng @rspress/plugin-twoslash, na nagdadala ng mas mayamang pagpapakita ng mga code block.
• Karanasan sa Pagbuo ng Dokumentasyon: Pinahusay ang HMR ng mga file tulad ng nav.json, meta.json at nagdagdag ng json schema para sa code hints sa IDE; default na pinagana ang dead link checking; nagdagdag ng syntax para sa mga file code block, sumusuporta sa pag-refer sa mga panlabas na file; @rspress/plugin-preview at @rspress/plugin-playground ay sumusuporta sa sabay na paggamit, atbp.
• Rslib Integration: Ngayon ay maaari nang pumili ng Rspress bilang tool sa dokumentasyon kapag gumagamit ng create-rslib upang lumikha ng mga proyekto ng component library, na mabilis na bumuo ng mga dokumentasyon na site para sa mga component.

2.0 Mga Bagong Tampok

Ganap na Bagong Tema

Ang default na tema ng 2.0 ay nakaranas ng isang sistematikong pag-upgrade, na dinisenyo ng team designer na si @Zovn Wei, na nagdala ng malaking pagtaas sa visual na epekto at karanasan sa pagbabasa, at bawat component ay maaaring palitan nang hiwalay, na may mataas na antas ng pag-customize.

Pag-customize ng Tema

Ayon sa antas ng pag-customize mula sa mababa hanggang mataas, mayroong apat na paraan ng pag-customize ng tema: CSS variables, BEM class names, ESM re-export overrides, at component eject.- CSS Variables: Ang bagong tema ay naglalantad ng mas maraming CSS variables, na sumasaklaw sa tema ng kulay, mga code block, at iba pang estilo ng homepage. Maaari mong i-preview at ayusin ang lahat ng CSS variables nang interaktibo sa CSS variables page, at kapag nahanap mo na ang nais na configuration, maaari mo itong kopyahin nang direkta sa iyong proyekto.

• BEM Class Names: Ang mga built-in na component ay gumagamit na ngayon ng BEM naming convention. Ito ay isang napaka Old School na pagpipilian, ngunit ito rin ay isang desisyon na pinag-isipan naming mabuti. Maaaring tumpak na ayusin ng mga user ang estilo gamit ang CSS selectors, at ang HTML structure ay mas malinaw.
• ESM Re-export Override: Kung ang mga pagbabago sa CSS ay hindi sapat para sa mga kinakailangan sa customization, maaari itong mas malalim na i-customize gamit ang JS. Sa theme/index.tsx, gamit ang ESM re-export, maaari mong i-override ang anumang built-in na component ng Rspress.
• Component Eject: Maaari mong gamitin ang bagong rspress eject [component] na utos, na kokopyahin ang source code ng tinukoy na component sa theme/components/ directory, at maaari mong malayang baguhin ang mga code na ito, kahit na direktang ipasa ito sa AI para sa mas malalim na customization.

Navigation Bar, Sidebar Tag

Ang Rspress 2.0 ay nagpatupad ng Tag component, at ngayon ay maaari nang gamitin ang tag property sa frontmatter para sa UI annotation sa sidebar o navigation bar.

Built-in Multilingual Support

Sa 1.x na bersyon, ang Rspress ay may built-in lamang na English text, at kung gumagamit ng ibang wika tulad ng zh, kinakailangan na i-configure ang lahat ng text, na medyo kumplikado. Ngayon, ang 2.0 tema ay may built-in na pagsasalin ng iba't ibang wika tulad ng zh, en, ja, ko, ru, atbp., at ang sistema ay awtomatikong nagsasagawa ng "Tree Shaking" batay sa configuration ng wika, na nag-iimpake lamang ng mga text at wika na iyong ginagamit.

llms.txt Support

Ngayon ay isinama ng Rspress ang kakayahan sa pagbuo ng llms.txt sa core, at nagpatupad ng bagong SSG-MD (Static Site Generation to Markdown) na kakayahan.

Sa mga front-end framework na nakabatay sa React, madalas na may problema sa pagkuha ng static na impormasyon, at ang Rspress ay nahaharap din sa parehong hamon. Pinapayagan ng Rspress ang mga user na palakasin ang dokumentasyon gamit ang MDX fragments, React components, Hooks, at TSX routing at iba pang dynamic na katangian. Ngunit ang mga dynamic na nilalaman na ito ay nahaharap sa mga sumusunod na problema kapag kinonvert sa Markdown text:

• Ang direktang pagbibigay ng MDX sa AI ay maglalaman ng maraming code syntax noise at mawawala ang nilalaman ng React components.
• Ang pag-convert ng HTML sa Markdown ay kadalasang hindi maganda ang resulta, at mahirap matiyak ang kalidad ng impormasyon.

Upang malutas ang problemang ito, ipinakilala ng Rspress 2.0 ang SSG-MD na katangian. Ito ay isang bagong tampok na katulad ng static site generation (SSG), ngunit ang pagkakaiba ay ito ay nag-render ng iyong mga pahina bilang Markdown files sa halip na HTML files, at bumubuo ng mga file na llms.txt at llms-full.txt.

Shiki Compilation Code Block HighlightRspress 2.0 ay default na gumagamit ng Shiki para sa syntax highlighting. Kumpara sa runtime highlighting solution ng 1.x na prism, ang Shiki ay nagtatapos ng highlighting processing sa compilation time.

• Sinusuportahan ang iba't ibang tema, tulad ng sa CSS variable page na maaari mong interaktibong palitan at i-preview ang iba't ibang Shiki themes.
• Kasabay nito, pinapayagan din ng Shiki ang paggamit ng custom transformer para sa pagpapayaman ng pagsusulat, tulad ng twoslash at iba pa.
• Nag-iimport ng programming languages ayon sa pangangailangan, hindi nagdaragdag ng runtime overhead at package size.
• Batay sa TextMate syntax, nagbibigay ng tumpak na syntax highlighting na katulad ng sa VS Code.

Pagpapabuti ng Performance ng Build

Ang Rspress 2.0 ay pinapagana ng Rsbuild at Rspack 2.0 preview version, at default na naka-enable ang on-demand compilation at persistent caching.

On-Demand Compilation

Default na naka-enable ang dev.lazyCompilation, tanging kapag binisita mo ang isang partikular na pahina, ang pahinang iyon lamang ang ikokompile, na lubos na nagpapabilis ng startup speed ng development, kahit na nagiging milliseconds ang cold start. Ang Rspress ay nagpatupad din ng preload strategy para sa routing, kapag ang mouse ay naka-hover sa link, ang target routing page ay preloaded, na may kasamang lazyCompilation para sa lossless na karanasan sa development.

Persistent Caching

Ang 2.0 ay default na naka-enable din ang persistent caching, na nire-reuse ang resulta ng huling compilation sa hot start, na nagpapabilis ng 30%-60% ng build speed. Ibig sabihin, pagkatapos ng unang pagtakbo ng rspress dev o rspress build, ang mga susunod na startup speed ay magiging kapansin-pansin na mas mabilis.

Karanasan sa Pag-develop ng Dokumento

Default na Naka-enable ang Dead Link Check

Ang Rspress 2.0 ay default na naka-enable ang dead link check feature. Sa proseso ng build, awtomatikong sine-check ang mga invalid links sa dokumento, na tumutulong sa iyo na agad na matukoy at ayusin ang mga ito.

File Code Blocks

Maaari mong gamitin ang file="./path/to/file" na attribute upang i-refer ang external file bilang nilalaman ng code block, na naglalagay ng sample code sa isang hiwalay na file para sa maintenance.

Mas Flexible na Paggamit ng Meta sa Preview

Ang @rspress/plugin-preview ay ngayon batay sa meta attribute, mas flexible, at maaari ring gamitin kasama ang file code blocks.

Rslib & Rspress

Sa paggamit ng create-rslib para lumikha ng proyekto, maaari mo nang piliin ang Rspress tool. Pinapayagan ka nitong mabilis na bumuo ng kasamang documentation site habang nag-de-develop ng component library, para sa pagsusulat ng mga usage instructions ng components, pagpapakita ng API reference, o real-time na pag-preview ng component effects.

Higit pang Opisyal na Plugin ng Rspress

Ang Rspress 2.0 ay nagdagdag ng maraming opisyal na plugin:

• @rspress/plugin-algolia: sumusuporta sa pagpapalit ng built-in search ng Rspress sa Algolia DocSearch
• @rspress/plugin-twoslash: nagdadagdag ng type hints para sa TypeScript code blocks
• @rspress/plugin-llms: nagbibigay ng llms.txt generation capability para sa mga proyektong hindi sumusuporta sa SSG at SSG-MD
• @rspress/plugin-sitemap: awtomatikong bumubuo ng Sitemap file para sa SEO optimization

Mga Breaking Changes

Migrasyon mula sa Rspress 1.x

Kung ikaw ay gumagamit ng 1.x na proyekto, naghanda kami ng detalyadong migration document upang tulungan kang mag-upgrade mula 1.x patungong 2.0. Maaari mong direktang gamitin ang "copy Markdown" na feature sa page, at ipasok ito sa iyong karaniwang coding agent (tulad ng Claude Code at iba pa) upang makumpleto ang migrasyon.### Node.js at mga Kinakailangan sa Bersyon ng Upstream Dependencies

Ang Rspress 2.0 ay nangangailangan ng bersyon ng Node.js na 20+, bersyon ng React na 18+.

Susunod na Hakbang

Ang paglulunsad ng Rspress 2.0 ay isang bagong simula lamang. Matapos ang paglulunsad na ito, ang Rspress ay patuloy na mag-iiterate:

• Pagsulong ng Ekosistema ng Integrasyon: Mas malalim na pagsasama sa Rslib, Rstest, na nagbibigay ng pinagsamang karanasan sa pagbuo ng mga proyekto sa frontend at mga proyekto ng component library.
• Pagsisiyasat ng AI at Mas Malalim na Integrasyon ng Dokumentasyon: Tulad ng matalinong pagtatanong, awtomatikong buod, atbp.; pagbutihin ang SSG-MD upang maging matatag at mas madaling gamitin.

Gamitin o i-upgrade na sa Rspress 2.0, maranasan ang bagong paglalakbay sa pagbuo ng dokumentasyon!

npm create rspress@latest