跳到主要內容
版本：3.5.2

安裝

Docusaurus 由一組 npm 套件 組成。

提示

使用 快速入門 在 5 分鐘內 ⏱ 了解 Docusaurus！

使用 docusaurus.new 在您的瀏覽器中立即測試 Docusaurus！

需求​

  • Node.js 版本 18.0 或更高版本（可以通過運行 node -v 檢查）。您可以使用 nvm 在一台機器上管理多個 Node 版本。
    • 安裝 Node.js 時，建議您勾選所有與依賴項相關的核取方塊。

搭建專案網站​

安裝 Docusaurus 最簡單的方法是使用命令列工具，它可以幫助您搭建 Docusaurus 網站框架。您可以在新的空儲存庫或現有儲存庫中的任何位置運行此命令，它將創建一個包含搭建檔案的新目錄。

npx create-docusaurus@latest my-website classic

我們建議使用 classic 範本，以便您可以快速上手，它包含 Docusaurus 1 中的功能。classic 範本包含 @docusaurus/preset-classic，其中包括標準文件、部落格、自訂頁面和 CSS 框架（支援深色模式）。您可以使用經典範本快速啟動並運行，並在您更加熟悉 Docusaurus 後再進行自訂。

您還可以通過傳遞 --typescript 旗標來使用範本的 TypeScript 變體。有關更多資訊，請參閱 TypeScript 支援。

npx create-docusaurus@latest my-website classic --typescript
僅限 Meta

如果您正在為 Meta 開源專案設置新的 Docusaurus 網站，請在內部儲存庫中運行此命令，該儲存庫附帶一些有用的 Meta 特定預設值

scarf static-docs-bootstrap
其他安裝命令

您也可以使用您喜歡的專案管理器初始化新專案

npm init docusaurus

運行 npx create-docusaurus@latest --help，或查看其 API 文件 以獲取有關所有可用旗標的更多資訊。

專案結構​

假設您選擇了經典範本並將您的網站命名為 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 組件。您不必嚴格將非文件檔案放在這裡，但是將它們放在集中目錄下可以更容易指定，以防您需要進行某種 lint/處理
    • /src/pages - 此目錄中的任何 JSX/TSX/MDX 檔案都將轉換為網站頁面。更多詳細資訊可以在 頁面指南 中找到
  • /static/ - 靜態目錄。此處的任何內容都將複製到最終 build 目錄的根目錄中
  • /docusaurus.config.js - 包含網站設定的設定檔。這相當於 Docusaurus v1 中的 siteConfig.js
  • /package.json - Docusaurus 網站是一個 React 應用程式。您可以在其中安裝和使用任何您喜歡的 npm 套件
  • /sidebars.js - 由文件使用，用於指定側邊欄中文檔的順序

Monorepos​

如果您正在使用 Docusaurus 為現有專案編寫文件，那麼 monorepo 可能是您的解決方案。Monorepos 允許您在類似專案之間共用依賴項。例如，您的網站可以使用您的本地套件來展示最新功能，而不是依賴已發布的版本。然後，您的貢獻者可以在實施功能時更新文件。下面是一個 monorepo 資料夾結構範例

my-monorepo
├── package-a # Another package, your actual project
│   ├── src
│   └── package.json # Package A's dependencies
├── website   # Docusaurus root
│   ├── docs
│   ├── src
│   └── package.json # Docusaurus' dependencies
├── package.json # Monorepo's shared dependencies

在這種情況下，您應該在 ./my-monorepo 資料夾中運行 npx create-docusaurus。

如果您使用的是 Netlify 或 Vercel 等託管服務提供商，則需要將網站的 Base directory 更改為您的 Docusaurus 根目錄所在的位置。在這種情況下，那將是 ./website。在 部署文件 中閱讀有關設定忽略命令的更多資訊。

在 Yarn 文件 中閱讀有關 monorepos 的更多資訊（Yarn 不是設置 monorepo 的唯一方法，但它是一種常見的解決方案），或者查看 Docusaurus 和 Jest 以獲取一些真實世界的範例。

運行開發伺服器​

要預覽您在編輯檔案時的更改，您可以運行一個本地開發伺服器，該伺服器將提供您的網站並反映最新的更改。

cd my-website
npm run start

默認情況下，瀏覽器窗口將在 https://127.0.0.1:3000 打開。

恭喜！您剛剛創建了您的第一個 Docusaurus 網站！瀏覽網站以查看可用內容。

構建​

Docusaurus 是一個現代化的靜態網站生成器，因此我們需要將網站構建到一個靜態內容目錄中，並將其放在 Web 伺服器上，以便可以查看它。要構建網站

npm run build

內容將在 /build 目錄中生成，該目錄可以複製到任何靜態檔案託管服務，例如 GitHub 頁面、Vercel 或 Netlify。查看有關 部署 的文件以獲取更多詳細資訊。

更新您的 Docusaurus 版本​

有很多方法可以更新您的 Docusaurus 版本。一種有保證的方法是手動將 package.json 中的版本號更改為所需的版本。請注意，所有 @docusaurus/ 命名空間的套件都應使用相同的版本。

package.json
{
  "dependencies": {
    "@docusaurus/core": "3.5.2",
    "@docusaurus/preset-classic": "3.5.2",
    // ...
  }
}

然後，在包含 package.json 的目錄中，運行您的套件管理器的安裝命令

npm install

要檢查更新是否成功，請運行

npx docusaurus --version

您應該看到正確的版本作為輸出。

或者，如果您使用的是 Yarn，則可以執行

yarn add @docusaurus/core @docusaurus/preset-classic
提示

使用 @canary npm dist 標籤 使用 Docusaurus 的新未發布功能

遇到問題？​

在 Stack Overflow、我們的 GitHub 儲存庫、我們的 Discord 伺服器 或 Twitter 上尋求幫助。

編輯此頁面
上次更新時間 由 Sébastien Lorber 更新