文章目錄
- 1. 簡介
- 2. 前提
- 2.1 安裝 git
- 2.2 安裝 node
- 3. 安裝
- 4. 項目結構
- 5. 訪問
- 5.1 localhost 訪問
- 5.2 ip 訪問
1. 簡介
Docusaurus 是一個facebook的開源項目，旨在幫助開發者構建易于維護和部署的文檔網站。它提供了一個簡單的方法來創建專業的文檔網站，包括易于導航的頁面、響應式設計和內置搜索功能。Docusaurus 非常適合開源項目、產品文檔、團隊內部文檔等各種場景。
Docusaurus 的主要特點包括：
- 易于使用：Docusaurus 提供了簡單的命令行工具和預設模板，使得創建和維護文檔網站變得輕而易舉。
- 響應式設計：文檔網站可以自適應不同的設備和屏幕尺寸，確保在桌面、平板和手機上都能提供良好的閱讀體驗。
- 內置搜索：Docusaurus 集成了強大的搜索功能，使用戶可以快速找到所需的文檔內容。
- 可定制性：開發者可以根據自己的需求定制主題、布局和樣式，以適應特定的品牌或風格。
- 社區支持：Docusaurus 擁有活躍的社區，提供了豐富的文檔和教程，幫助用戶快速上手并解決問題。
總的來說，Docusaurus 是一個強大而靈活的工具，可以幫助開發者輕松構建漂亮、實用的文檔網站，從而更好地展示和傳播他們的項目或產品。
2. 前提
2.1 安裝 git
1. 安裝依賴```bash
yum -y upgrade
sudo yum -y install wget make autoconf automake cmake perl-CPAN libcurl-devel libtool gcc gcc-c++ glibc-headers zlib-devel git-lfs telnet lrzsz jq expat-devel openssl-devel
- 安裝 Git
cd /tmp
wget --no-check-certificate https://mirrors.edge.kernel.org/pub/software/scm/git/git-2.45.0.tar.gz
tar -xvzf git-2.45.0.tar.gz
cd git-2.45.0/
./configure
make
sudo make install
按照上面的步驟安裝好之后，我們要把 Git 的二進制目錄添加到 PATH 路徑中，不然 Git 可能會因為找不到一些命令而報錯。你可以通過執行以下命令添加目錄：
tee -a $HOME/.bashrc <<'EOF'
# Configure for git
export PATH=/usr/local/libexec/git-core:$PATH
EOF
source $HOME/.bashrc
$ git --version # 輸出 git 版本號，說明安裝成功
git version 2.45.0
git config --global user.name "ghostwritten"
git config --global user.email "1zoxun1@gmail.com"
git config --global credential.helper store
git config --global core.longpaths true
git config --global core.quotepath off
git lfs install --skip-repo2.2 安裝 node
- 安裝 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
- 安裝node
nvm install node
查看版本
$ node --version
v22.1.0
3. 安裝
使用命令行工具可以幫助你快速簡單地安裝 Docusaurus 并搭建網站框架。 你可以在空倉庫或現有倉庫的任何地方運行這個命令，它會創建一個包含模板文件的新目錄。
npx create-docusaurus@latest upmdocs classic
Need to install the following packages:
create-docusaurus@3.3.2
Ok to proceed? (y) y? Which language do you want to use? ? JavaScript
[INFO] Creating new Docusaurus project...
[INFO] Installing dependencies with npm...added 1193 packages, and audited 1194 packages in 53s296 packages are looking for fundingrun `npm fund` for detailsfound 0 vulnerabilities
[SUCCESS] Created upmdocs.
[INFO] Inside that directory, you can run several commands:`npm start`Starts the development server.`npm run build`Bundles your website into static files for production.`npm run serve`Serves the built website locally.`npm run deploy`Publishes the website to GitHub pages.We recommend that you begin by typing:`cd upmdocs``npm start`Happy building awesome websites!推薦使用 classic 模板來快速上手，同時它也包含 Docusaurus 1 中的功能。 classic 模板內含 @docusaurus/preset-classic 包，后者包含了標準文檔、博客、自定義頁面及 CSS 框架（支持暗黑模式）。 你可以用經典模板來快速設立網站，在熟悉了 Docusaurus 之后，再逐步對其自定義。
你也可以用 --typescript 選項來使用模板的 TypeScript 變種。 更多詳情請查看 Typescript 支持。
npx create-docusaurus@latest my-website classic --typescript
4. 項目結構
假設你選擇了經典模板并將網站命名為 my-website，你將會在新目錄 my-website/ 下看到下列文件：
my-website
├── blog
│ ├── 2019-05-28-hola.md
│ ├── 2019-05-29-hello-world.md
│ └── 2020-05-30-welcome.md
├── docs
│ ├── doc1.md
│ ├── doc2.md
│ ├── doc3.md
│ └── mdx.md
├── src
│ ├── css
│ │ └── custom.css
│ └── pages
│ ├── styles.module.css
│ └── index.js
├── static
│ └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock
項目結構解讀
/blog/- 包含博客的 Markdown 文件。 如果你后續禁用了博客插件，你可以刪除這個目錄，或者你也可以在設置 path 選項之后修改它的名稱。 詳情可參考博客指南/docs/- 包含文檔的 Markdown 文件。 你可以在 sidebars.js 中自定義文檔的側邊欄順序。 如果你后續禁用了文檔插件，你可以刪除這個目錄，或者你也可以在設置 path 選項之后修改它的名稱。 詳情可參考文檔指南/src/- 如頁面或自定義 React 組件一類的非文檔文件。 嚴格來說，你不一定要把非文檔類文件放在這里。不過把它們放在一個集中的目錄，可以讓代碼檢查或者處理更為簡便。/src/pages- 所有放在此目錄中的 JSX/TSX/MDX 文件都會被轉換成網站頁面。 詳情可參考頁面指南
/static/- 靜態目錄。 此處的所有內容都會被復制進 build 文件夾/docusaurus.config.js- 站點配置文件。 這等效于 Docusaurus 1 中的 siteConfig.js 文件/package.json- Docusaurus 網站是一個 React 應用。 你可以安裝并使用任何 npm 包。/sidebars.js- 由文檔使用，用于指定側邊欄中的文檔順序
5. 訪問
5.1 localhost 訪問
$ npm start> upmdocs@0.0.0 start
> docusaurus start[INFO] Starting the development server...
(node:11880) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(Use `node --trace-deprecation ...` to show where the warning was created)
[SUCCESS] Docusaurus website is running at: http://localhost:3000/? ClientCompiled successfully in 1.13sclient (webpack 5.91.0) compiled successfully
注意：只能 http://localhost:3000/ 訪問，無法 http://ip:3000/訪問
5.2 ip 訪問
$ npm run serve -- --build --port 3000 --host 0.0.0.0> upmdocs@0.0.0 serve
> docusaurus serve --build --port 3000 --host 0.0.0.0(node:10452) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(Use `node --trace-deprecation ...` to show where the warning was created)
[INFO] [en] Creating an optimized production build...? ClientCompiled successfully in 11.36s? Server● Client █████████████████████████ cache (99%) shutdown IdleFileCachePluginstored? Server[SUCCESS] Generated static files in "build".
[INFO] Use `npm run serve` command to test your build locally.
[SUCCESS] Serving "build" directory at: http://0.0.0.0:3000/
參考：
- https://docusaurus.io/zh-CN/docs/next
- https://docusaurus.io/
)
)
