改版3.0.0
· 閱讀時間約 4 分鐘
剛使用Docusaurus之後,就突然釋出3.0.0了...
趁著現在內容還沒有很多的時候趕快升上去,避免之後又需要調整很多內容。
2023/11/06
因為想要測試interactive clde editor,安裝的時候又一直跟我說相依套件有問題。
所以果斷直接升到3.0了...
基本差異
因為我目前剛開始使用,其實也感受不到太大的差異。官方說明是說react
以及node
都有版本上的更新。我個人在使用上遇到最大的問題是MDX
上解析語法與之前會有所不同,導致我有一些.md
文件會編譯錯誤。
更新方式
官方文件 | official
我在更新的時候是直接刪除整個node_module
檔案,接著按照官方說明的將package.json更新如下:
package.json
{
"dependencies": {
// upgrade to Docusaurus v3
- "@docusaurus/core": "2.4.3",
- "@docusaurus/preset-classic": "2.4.3",
+ "@docusaurus/core": "3.0.0",
+ "@docusaurus/preset-classic": "3.0.0",
// upgrade to MDX v2
- "@mdx-js/react": "^1.6.22",
+ "@mdx-js/react": "^3.0.0",
// upgrade to prism-react-renderer v2.0+
- "prism-react-renderer": "^1.3.5",
+ "prism-react-renderer": "^2.1.0",
// upgrade to React v18.0+
- "react": "^17.0.2",
- "react-dom": "^17.0.2"
+ "react": "^18.2.0",
+ "react-dom": "^18.2.0"
},
"devDependencies": {
// upgrade Docusaurus dev dependencies to v3
- "@docusaurus/module-type-aliases": "2.4.3"
- "@docusaurus/types": "2.4.3"
+ "@docusaurus/module-type-aliases": "3.0.0"
+ "@docusaurus/types": "3.0.0"
}
"engines": {
// require Node.js 18.0+
- "node": ">=16.14"
+ "node": ">=18.0"
}
}
接著重新使用sudo npm install
去安裝相關的套件,這時候可能會有一些衝突或者是之前的快取部分報錯。這部分我都直接--foce
覆蓋過去。
在安裝過後,先使用npm star
t測試看看有沒有順利跑成功,發現還是有幾個錯誤需要修正
prism
首先就是prism
在docusaurus.config.js
內的設定需要修改
修改方式參考 | Official
MDX Checker CLI
再來就是前面有提到的,因為MDX在語法解析上的關係,如果內文有使用到<
或是 {}
,都需要額外再調整。
可以透過運行以下指令,去看一下哪些文件在編譯時會出現問題。
npx docusaurus-mdx-checker
基本上解決的方式官方文件內都有提到,我自己是都使用跳脫字元(\
)去解決。
附上官方提供的錯誤修正方式:
https://docusaurus.io/zh-CN/docs/migration/v3#common-mdx-problems
處理錯誤資訊後
再處理錯誤資訊之後。我們可以試著運行npm run build
,嘗試建立靜態檔案。基本上我坐到這邊就沒有額外的問題了。