者文檔站點構(gòu)建與部署完全指南：基于 Docusaurus 的本地開發(fā)、靜態(tài)構(gòu)建與發(fā)布)
Diem 開發(fā)者文檔站點構(gòu)建與部署完全指南基于 Docusaurus 的本地開發(fā)、靜態(tài)構(gòu)建與發(fā)布【免費下載鏈接】diemDiem’s mission is to build a trusted and innovative financial network that empowers people and businesses around the world.項目地址: https://gitcode.com/gh_mirrors/di/diemDiem 開發(fā)者文檔網(wǎng)站developers.diem.com是 Diem 區(qū)塊鏈項目的官方技術(shù)文檔門戶基于 Docusaurus 靜態(tài)站點生成器構(gòu)建。本文以倉庫中的 developers.diem.com/src/README.md 為主體結(jié)合 developers.diem.com/package.json、developers.diem.com/scripts/build_docs.sh 與 developers.diem.com/docusaurus.config.js 等源碼級細節(jié)完整講解如何搭建本地開發(fā)環(huán)境、啟動熱更新服務(wù)器、自動生成 Rustdoc 與 Python SDK 的 API 參考文檔、產(chǎn)出靜態(tài)構(gòu)建產(chǎn)物并發(fā)布上線。讀完本文你將能獨立完成 Diem 文檔站點的構(gòu)建、預(yù)覽與部署全流程。文檔站點概覽從website到developers.diem.com原 README 中提到的website目錄是早期版本的歷史路徑在當前倉庫中該文檔站點實際位于 developers.diem.com 目錄下。這一點可以從構(gòu)建腳本得到印證scripts/build_docs.sh 在啟動時會強制檢查當前目錄名是否為developers.diem.com否則直接報錯退出。因此本文所有命令均以該目錄為基準。站點本身是一個 Docusaurus 項目當前 package.json 聲明使用docusaurus/core與docusaurus/preset-classic的^2.0.0-beta.4版本文檔內(nèi)容分布在docs/教程、參考、技術(shù)論文、blog/官方技術(shù)博客與src/自定義 React 組件與主題中側(cè)邊欄結(jié)構(gòu)由 sidebars/index.js 定義。此外站點還集成了 Algolia 站內(nèi)搜索索引名為diem_developer_website與 Google Analytics相關(guān)配置見 docusaurus.config.js。環(huán)境準備Node 與 Yarn 版本要求根據(jù) developers.diem.com/src/README.md構(gòu)建該站點需要滿足以下工具鏈Node.js 8.xDocusaurus 運行時的 JavaScript 運行時Yarn 1.5包管理器用于安裝依賴與執(zhí)行docusaurus相關(guān)腳本。需要說明的是這是文檔聲明的基礎(chǔ)版本門檻鑒于項目實際依賴 Docusaurus 2.0 beta 版本見 package.json實踐上建議使用更新的 Node.js 長期支持版本以獲得最佳兼容性。依賴安裝通過yarn install完成倉庫根目錄已附帶 yarn.lock 鎖定精確依賴版本保證可復(fù)現(xiàn)構(gòu)建。本地開發(fā)啟動開發(fā)服務(wù)器在滿足環(huán)境要求后進入developers.diem.com目錄并啟動 Docusaurus 開發(fā)服務(wù)器cd developers.diem.com yarn startyarn start對應(yīng) package.json 中的docusaurus start腳本。啟動成功后瀏覽器會自動打開http://localhost:3000若未自動打開請手動訪問該地址開發(fā)服務(wù)器支持實時熱更新任何時候修改頁面內(nèi)容如docs/下的 Markdown 或src/下的組件頁面會自動重新編譯并刷新無需手動重啟這是日常撰寫文檔、調(diào)試組件時最常用的工作流。如果希望啟用無障礙Accessibility檢查模式package.json中還提供了yarn start-with-ada對應(yīng)TEST_ADA1 docusaurus start它會結(jié)合 axe-core/react 在開發(fā)階段對頁面進行可訪問性審計適合在提交面向公眾的文檔改動前使用。生成 API 參考文檔Rustdoc 與 Python SDKyarn start只編譯 Markdown 文檔與網(wǎng)站本身不會重新生成 API 參考頁面。API 參考由 Rustdoc 與 Protogen 自動生成原 README 明確說明因此需要額外的構(gòu)建步驟。倉庫中的 scripts/build_docs.sh 提供了完整的自動生成能力其支持的參數(shù)如下參數(shù)作用-b構(gòu)建靜態(tài)版本文檔否則啟動開發(fā)服務(wù)器-r構(gòu)建 Diem Rust crate 的文檔Rustdoc-p構(gòu)建 Diem Python Client SDK 文檔-h顯示幫助信息運行構(gòu)建腳本在developers.diem.com目錄下執(zhí)行./scripts/build_docs.sh該腳本的核心邏輯分為三部分安裝 Rust 工具鏈腳本會檢查rustup是否可用缺失時通過curl https://sh.rustup.rs -sSf安裝默認 stable 工具鏈build_docs.sh#L21-L29生成 Rustdoc-r腳本切回倉庫根目錄使用以下命令為整個 workspace 生成 crate 文檔RUSTC_BOOTSTRAP1 RUSTDOCFLAGS-Z unstable-options --enable-index-page cargo doc --no-deps --workspace --lib其中RUSTC_BOOTSTRAP與--enable-index-page用于為 workspace 生成index.html著陸頁。產(chǎn)物位于target/doc/隨后被復(fù)制到static/docs/rustdocs/build_docs.sh#L84-L105生成 Python SDK 文檔-p腳本要求 Python 3.7創(chuàng)建虛擬環(huán)境后安裝diem-client-sdk與pdoc3再以pdoc3 diem --html生成文檔到static/docs/python-client-sdk-docs/build_docs.sh#L107-L134。完成 API 參考生成后腳本統(tǒng)一執(zhí)行yarn install并進入下一步構(gòu)建。生成靜態(tài)構(gòu)建產(chǎn)物要將網(wǎng)站構(gòu)建為可直接部署的靜態(tài)文件輸出到website/build目錄使用-b參數(shù)./scripts/build_docs.sh -b在-b模式下腳本執(zhí)行yarn build對應(yīng) package.json 中的NODE_ENVproduction docusaurus build生成生產(chǎn)環(huán)境優(yōu)化后的靜態(tài)站點。值得注意的是倉庫中同時提供了 vercel.json為所有頁面配置了X-Robots-Tag: noindex響應(yīng)頭——這是 Vercel 預(yù)覽部署環(huán)境下防止文檔站點被搜索引擎收錄的工程化細節(jié)可作為部署配置的參考。另外docusaurus.config.js 中注冊了docusaurus/plugin-client-redirects重定向插件任何包含/overview的路徑都會被追加生成一條去掉/overview的等價路徑用于兼容舊版 URL保證歷史鏈接不失效。部署與分發(fā)打包上傳與服務(wù)器解壓開發(fā)或預(yù)覽構(gòu)建完成后如需在更廣范圍內(nèi)進行測試原 README 給出了經(jīng)典的打包分發(fā)流程。首先在倉庫根目錄或文檔站點上級目錄將構(gòu)建產(chǎn)物壓縮zip diem.zip -r website/build隨后通過scp將壓縮包上傳到目標服務(wù)器scp -r website/build/ userserver:/path在服務(wù)器上解壓即可完成部署unzip diem.zip這種方式適合臨時測試環(huán)境或無法直接推送靜態(tài)文件的場景。需要提醒的是當前倉庫中靜態(tài)構(gòu)建的實際輸出目錄以yarn build的 Docusaurus 配置為準baseUrl為/見 docusaurus.config.js實際部署時應(yīng)以構(gòu)建后生成的真實目錄為準進行打包。發(fā)布GitHub Pages 與持續(xù)發(fā)布原 README 說明網(wǎng)站的正式發(fā)布通過 GitHub Pages 承載發(fā)布目標為獨立網(wǎng)站倉庫的gh-pages分支。其流程大致為將靜態(tài)構(gòu)建產(chǎn)物提交/推送到gh-pages分支由 GitHub Pages 自動對外提供服務(wù)。與此同時docusaurus.config.js 中為文檔與博客分別配置了editUrl指向 Diem 主倉庫的developers.diem.com/路徑這意味著 Docusaurus 會在每個頁面上渲染編輯此頁鏈接方便社區(qū)讀者直接跳轉(zhuǎn)到源碼提交文檔修改——這是文檔站點維護協(xié)作的重要入口。此外package.json 還提供了deploy-staging腳本npm run build-staging npx now用于構(gòu)建 staging 版本并發(fā)布到 Vercel 平臺進行預(yù)發(fā)布驗證配合上文提到的noindex頭使用屬于正式發(fā)布前的重要質(zhì)量關(guān)卡?？偨Y(jié)Diem 開發(fā)者文檔站點雖然是一個文檔項目但其工程化程度與主代碼庫相當本地開發(fā)有熱更新、API 參考有自動生成腳本、部署有靜態(tài)構(gòu)建與多渠道發(fā)布。核心操作路徑可歸納為三條日常寫作cd developers.diem.com yarn start訪問http://localhost:3000實時預(yù)覽完整構(gòu)建./scripts/build_docs.sh必要時追加-r/-p生成 API 參考追加-b輸出靜態(tài)產(chǎn)物發(fā)布部署將構(gòu)建產(chǎn)物打包上傳解壓或通過gh-pages分支 / Vercel staging 渠道發(fā)布。掌握以上流程無論是為 Diem 貢獻文檔、構(gòu)建本地開發(fā)預(yù)覽還是搭建完整的文檔發(fā)布管線都能在 developers.diem.com 目錄下獨立完成?！久赓M下載鏈接】diemDiem’s mission is to build a trusted and innovative financial network that empowers people and businesses around the world.項目地址: https://gitcode.com/gh_mirrors/di/diem創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Diem 開發(fā)者文檔站點構(gòu)建與部署完全指南：基于 Docusaurus 的本地開發(fā)、靜態(tài)構(gòu)建與發(fā)布
Diem 開發(fā)者文檔站點構(gòu)建與部署完全指南基于 Docusaurus 的本地開發(fā)、靜態(tài)構(gòu)建與發(fā)布【免費下載鏈接】diemDiem’s mission is to build a trusted and innovative financial network that empowers people and businesses around the world.項目地址: https://gitcode.com/gh_mirrors/di/diemDiem 開發(fā)者文檔網(wǎng)站developers.diem.com是 Diem 區(qū)塊鏈項目的官方技術(shù)文檔門戶基于 Docusaurus 靜態(tài)站點生成器構(gòu)建。本文以倉庫中的 developers.diem.com/src/README.md 為主體結(jié)合 developers.diem.com/package.json、developers.diem.com/scripts/build_docs.sh 與 developers.diem.com/docusaurus.config.js 等源碼級細節(jié)完整講解如何搭建本地開發(fā)環(huán)境、啟動熱更新服務(wù)器、自動生成 Rustdoc 與 Python SDK 的 API 參考文檔、產(chǎn)出靜態(tài)構(gòu)建產(chǎn)物并發(fā)布上線。讀完本文你將能獨立完成 Diem 文檔站點的構(gòu)建、預(yù)覽與部署全流程。文檔站點概覽從website到developers.diem.com原 README 中提到的website目錄是早期版本的歷史路徑在當前倉庫中該文檔站點實際位于 developers.diem.com 目錄下。這一點可以從構(gòu)建腳本得到印證scripts/build_docs.sh 在啟動時會強制檢查當前目錄名是否為developers.diem.com否則直接報錯退出。因此本文所有命令均以該目錄為基準。站點本身是一個 Docusaurus 項目當前 package.json 聲明使用docusaurus/core與docusaurus/preset-classic的^2.0.0-beta.4版本文檔內(nèi)容分布在docs/教程、參考、技術(shù)論文、blog/官方技術(shù)博客與src/自定義 React 組件與主題中側(cè)邊欄結(jié)構(gòu)由 sidebars/index.js 定義。此外站點還集成了 Algolia 站內(nèi)搜索索引名為diem_developer_website與 Google Analytics相關(guān)配置見 docusaurus.config.js。環(huán)境準備Node 與 Yarn 版本要求根據(jù) developers.diem.com/src/README.md構(gòu)建該站點需要滿足以下工具鏈Node.js 8.xDocusaurus 運行時的 JavaScript 運行時Yarn 1.5包管理器用于安裝依賴與執(zhí)行docusaurus相關(guān)腳本。需要說明的是這是文檔聲明的基礎(chǔ)版本門檻鑒于項目實際依賴 Docusaurus 2.0 beta 版本見 package.json實踐上建議使用更新的 Node.js 長期支持版本以獲得最佳兼容性。依賴安裝通過yarn install完成倉庫根目錄已附帶 yarn.lock 鎖定精確依賴版本保證可復(fù)現(xiàn)構(gòu)建。本地開發(fā)啟動開發(fā)服務(wù)器在滿足環(huán)境要求后進入developers.diem.com目錄并啟動 Docusaurus 開發(fā)服務(wù)器cd developers.diem.com yarn startyarn start對應(yīng) package.json 中的docusaurus start腳本。啟動成功后瀏覽器會自動打開http://localhost:3000若未自動打開請手動訪問該地址開發(fā)服務(wù)器支持實時熱更新任何時候修改頁面內(nèi)容如docs/下的 Markdown 或src/下的組件頁面會自動重新編譯并刷新無需手動重啟這是日常撰寫文檔、調(diào)試組件時最常用的工作流。如果希望啟用無障礙Accessibility檢查模式package.json中還提供了yarn start-with-ada對應(yīng)TEST_ADA1 docusaurus start它會結(jié)合 axe-core/react 在開發(fā)階段對頁面進行可訪問性審計適合在提交面向公眾的文檔改動前使用。生成 API 參考文檔Rustdoc 與 Python SDKyarn start只編譯 Markdown 文檔與網(wǎng)站本身不會重新生成 API 參考頁面。API 參考由 Rustdoc 與 Protogen 自動生成原 README 明確說明因此需要額外的構(gòu)建步驟。倉庫中的 scripts/build_docs.sh 提供了完整的自動生成能力其支持的參數(shù)如下參數(shù)作用-b構(gòu)建靜態(tài)版本文檔否則啟動開發(fā)服務(wù)器-r構(gòu)建 Diem Rust crate 的文檔Rustdoc-p構(gòu)建 Diem Python Client SDK 文檔-h顯示幫助信息運行構(gòu)建腳本在developers.diem.com目錄下執(zhí)行./scripts/build_docs.sh該腳本的核心邏輯分為三部分安裝 Rust 工具鏈腳本會檢查rustup是否可用缺失時通過curl https://sh.rustup.rs -sSf安裝默認 stable 工具鏈build_docs.sh#L21-L29生成 Rustdoc-r腳本切回倉庫根目錄使用以下命令為整個 workspace 生成 crate 文檔RUSTC_BOOTSTRAP1 RUSTDOCFLAGS-Z unstable-options --enable-index-page cargo doc --no-deps --workspace --lib其中RUSTC_BOOTSTRAP與--enable-index-page用于為 workspace 生成index.html著陸頁。產(chǎn)物位于target/doc/隨后被復(fù)制到static/docs/rustdocs/build_docs.sh#L84-L105生成 Python SDK 文檔-p腳本要求 Python 3.7創(chuàng)建虛擬環(huán)境后安裝diem-client-sdk與pdoc3再以pdoc3 diem --html生成文檔到static/docs/python-client-sdk-docs/build_docs.sh#L107-L134。完成 API 參考生成后腳本統(tǒng)一執(zhí)行yarn install并進入下一步構(gòu)建。生成靜態(tài)構(gòu)建產(chǎn)物要將網(wǎng)站構(gòu)建為可直接部署的靜態(tài)文件輸出到website/build目錄使用-b參數(shù)./scripts/build_docs.sh -b在-b模式下腳本執(zhí)行yarn build對應(yīng) package.json 中的NODE_ENVproduction docusaurus build生成生產(chǎn)環(huán)境優(yōu)化后的靜態(tài)站點。值得注意的是倉庫中同時提供了 vercel.json為所有頁面配置了X-Robots-Tag: noindex響應(yīng)頭——這是 Vercel 預(yù)覽部署環(huán)境下防止文檔站點被搜索引擎收錄的工程化細節(jié)可作為部署配置的參考。另外docusaurus.config.js 中注冊了docusaurus/plugin-client-redirects重定向插件任何包含/overview的路徑都會被追加生成一條去掉/overview的等價路徑用于兼容舊版 URL保證歷史鏈接不失效。部署與分發(fā)打包上傳與服務(wù)器解壓開發(fā)或預(yù)覽構(gòu)建完成后如需在更廣范圍內(nèi)進行測試原 README 給出了經(jīng)典的打包分發(fā)流程。首先在倉庫根目錄或文檔站點上級目錄將構(gòu)建產(chǎn)物壓縮zip diem.zip -r website/build隨后通過scp將壓縮包上傳到目標服務(wù)器scp -r website/build/ userserver:/path在服務(wù)器上解壓即可完成部署unzip diem.zip這種方式適合臨時測試環(huán)境或無法直接推送靜態(tài)文件的場景。需要提醒的是當前倉庫中靜態(tài)構(gòu)建的實際輸出目錄以yarn build的 Docusaurus 配置為準baseUrl為/見 docusaurus.config.js實際部署時應(yīng)以構(gòu)建后生成的真實目錄為準進行打包。發(fā)布GitHub Pages 與持續(xù)發(fā)布原 README 說明網(wǎng)站的正式發(fā)布通過 GitHub Pages 承載發(fā)布目標為獨立網(wǎng)站倉庫的gh-pages分支。其流程大致為將靜態(tài)構(gòu)建產(chǎn)物提交/推送到gh-pages分支由 GitHub Pages 自動對外提供服務(wù)。與此同時docusaurus.config.js 中為文檔與博客分別配置了editUrl指向 Diem 主倉庫的developers.diem.com/路徑這意味著 Docusaurus 會在每個頁面上渲染編輯此頁鏈接方便社區(qū)讀者直接跳轉(zhuǎn)到源碼提交文檔修改——這是文檔站點維護協(xié)作的重要入口。此外package.json 還提供了deploy-staging腳本npm run build-staging npx now用于構(gòu)建 staging 版本并發(fā)布到 Vercel 平臺進行預(yù)發(fā)布驗證配合上文提到的noindex頭使用屬于正式發(fā)布前的重要質(zhì)量關(guān)卡?？偨Y(jié)Diem 開發(fā)者文檔站點雖然是一個文檔項目但其工程化程度與主代碼庫相當本地開發(fā)有熱更新、API 參考有自動生成腳本、部署有靜態(tài)構(gòu)建與多渠道發(fā)布。核心操作路徑可歸納為三條日常寫作cd developers.diem.com yarn start訪問http://localhost:3000實時預(yù)覽完整構(gòu)建./scripts/build_docs.sh必要時追加-r/-p生成 API 參考追加-b輸出靜態(tài)產(chǎn)物發(fā)布部署將構(gòu)建產(chǎn)物打包上傳解壓或通過gh-pages分支 / Vercel staging 渠道發(fā)布。掌握以上流程無論是為 Diem 貢獻文檔、構(gòu)建本地開發(fā)預(yù)覽還是搭建完整的文檔發(fā)布管線都能在 developers.diem.com 目錄下獨立完成?！久赓M下載鏈接】diemDiem’s mission is to build a trusted and innovative financial network that empowers people and businesses around the world.項目地址: https://gitcode.com/gh_mirrors/di/diem創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考