創建和自定義 Docusaurus 站點（具有博客功能）

對於輕量級網站、應用程序和其他小型項目，越來越多的開發人員轉向通過 WordPress 或其他內容管理系統 (CMS) 生成靜態站點。 靜態站點提供了一種簡單有效的方法來創建快速、安全且易於維護的網站和應用程序。

Docusaurus 就是這樣一種靜態站點生成器——它在開發社區中迅速流行起來。 厭倦了緩慢的內容管理系統？ 認識文檔龍！ 一個靜態站點生成器，可以在不減慢您速度的情況下完成工作。 繼續閱讀以了解更多信息點擊鳴叫

在這篇文章中，我們將深入探討使用 Docusaurs 作為靜態站點生成器的好處，以及為什麼它越來越受到開發人員的喜愛。

什麼是文檔龍？

Docusaurus 是一種流行的靜態站點生成器，它使用頂級 JavaScript 庫之一的 React 作為其用於創建頁面的 UI 庫。 與其他此類生成器一樣，它易於設置和修改，而且 - 最重要的是 - 它為您提供了啟動靜態網站所需的一切。

然而，讓 Docusaurus 與眾不同的是，它可以幫助您創建和管理內容起關鍵作用的網站。 它使您可以快速輕鬆地構建一個完整的網站——包括博客功能——從一開始就突出您的內容。

因為內容是 Docusaurus 的焦點，所以它非常適合創建 wiki 等文檔站點。 它還利用 markdown，這是協作和存儲在 git 存儲庫中的理想選擇。 更重要的是，它有很多令人驚奇的特性，比如 i18n、搜索和自定義主題，我們將在稍後詳細討論這些特性。

以下是使 Docusaurus 成為可靠選擇的一些突出功能：

• 使用 React 構建
• 支持 MDX v1
• 支持通過 Markdown 嵌入 React 組件
• 文檔版本控制
• 與 Git、Crowdin 和其他翻譯管理器兼容，用於文檔翻譯和批量或單獨部署

誰使用 Docusaurus？

Docusaurus 由 Facebook 創建，因此目前網絡上的許多大品牌和公司都在使用它也就不足為奇了。

以下是當今使用 Docusaurus 的幾個最大品牌（隨著 Docusaurus 的受歡迎程度持續增長，很快就會有更多品牌出現）：

• Algolia 文檔搜索
• 笑話
• 反應本機
• 超級基地

每天都有更多人加入他們的行列。

如何安裝 Docusaurus

Docusaurus 安裝非常簡單，只需要幾分鐘。 在本教程中，我們將構建一個帶有博客的文檔站點，並且我們將自定義該網站的外觀。

這是最酷的部分：我們將花費不到一個小時的時間來啟動所有內容。

讓我們開始吧！

要求

Docusarus 需要 Node.js 16.14 或更新版本。 它是一個平面文件 SSG，這意味著您不需要額外的數據庫。

如果您還沒有可用的 Node.js 16.14+，則需要先安裝 Node.js 或升級當前版本。 然後你可以繼續下面的 Docusaurus 安裝過程。

我們還將使用來自此 GitHub 存儲庫的示例 Docusaurus 網站。 您可以在本教程中使用它或全新安裝的 Docusaurus。

安裝過程

要開始 Docusaurus 安裝過程，您首先需要運行以下命令：

 npx [email protected] classic

這將為您的項目創建一個文件夾，並在其中構建經典主題。 經典主題已經包含一些預配置的功能，如博客、自定義頁面和 CSS 框架。

安裝完成後，您需要運行以下命令來啟動本地服務器：

 npm start

如果你想構建一個可以部署的優化版本，你應該運行它：

 npm run build

結構

安裝 Docusaurus 實例後，您將能夠打開項目目錄並仔細查看新站點的“骨架”。

文件結構如下所示：

 my-website ├── blog │ ├── 2019-05-28-hola.md │ └── 2020-05-30-welcome.md ├── docs │ ├── doc1.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 ：包含與您的博客相關的所有文件。
• /docs ：包含與您的文檔相關的所有文件。 您可以在sidebar.js文件中自定義它們的順序。
• /src ：包含所有非文檔文件，如頁面或自定義組件。
• /src/pages ：所有 JSX/TSX/MDX 文件都將轉換為頁面。
• /static ：將被複製到最終構建文件夾的靜態文件。
• docusaurus.config.js : Docusaurus 配置文件。
• packaged.json ：每個 Docusaurus 站點都是一個 React 應用程序，因此您可以在這裡找到它用於 React 的所有依賴項和腳本。
• sidebar.js ：在這裡你可以指定側邊欄中文檔的順序。

自定義您的 Docusaurus 安裝

從文件結構的簡單性可以看出，Docusaurus 易於使用和導航。 同樣，自定義您的 Docusaurus 網站也輕而易舉。 您可以使用您喜歡的文本編輯器或 IDE 打開和編輯這些文件。

讓我們回顧一下開箱即用的一些自定義選項。

主頁

您可能會渴望做的第一件事是自定義默認主頁來展示您自己的項目。 幸運的是，對 Docusaurus 主頁進行任何您想要的更改並不復雜。

要更改主頁，請打開src/pages/index.js文件並在其中進行調整。 這是一個典型的 React 頁面，因此您可以通過更改內容或創建自定義 React 組件來更改或重建它。

配置文件

接下來，我們將深入研究關鍵的docusaurus.config.js文件並為我們的實例更改一些重要的細節。

名稱和描述

在配置文件中，您會發現：

 const config = { title: 'My Site', tagline: 'Dinosaurs are cool', url: 'https://your-docusaurus-site.com', baseUrl: '/',

只需更改這些詳細信息以滿足您網站的需要，然後保存文件。

導航欄

要編輯導航欄，請找到navbar項目。

對於此處的示例，我們要添加一個指向 Kinsta 的鏈接，將“教程”項重命名為“入門文檔”，並添加 Kinsta 徽標。

以下是我們的處理方式：

 navbar: { title: 'Kinsta starters', logo: { alt: 'Kinsta Logo', src: 'img/kinsta-logo-alpha-purple.png', }, items: [ { label: 'Kinsta starters', to: '/docs/intro', }, {to: '/blog', label: 'Blog', position: 'left'}, { href: 'https://github.com/kinsta', label: 'GitHub', position: 'right', }, ], },

頁腳

Docusaurus 中的頁腳自定義由兩部分組成：頁腳內容本身和頁腳鍊接。

頁腳內容

您的大部分頁腳內容（不包括鏈接列表）可以放在您的themeConfig.footer文件中。 這是添加徽標和版權聲明的理想位置。

以下是我們修改頁腳配置的方式：

 module.exports = { themeConfig: { footer: { logo: { alt: 'Kinsta Logo', src: 'img/kinsta-logo.png', href: 'https://kinsta.com', width: 160, height: 51, }, copyright: `Copyright ${new Date().getFullYear()} Kinsta. Built with Docusaurus.`, }, }, };

頁腳鍊接

更改頁腳鍊接類似於更改頂部導航欄：在docusaurus.config.js中找到footer部分並進行編輯，直到它符合您的需要。

這是我們將footer部分更改為如下所示：

 footer: { style: 'dark', links: [ { title: 'Docs', items: [ { label: 'Kinsta starters', to: '/docs/intro', }, ], }, { title: 'Talk with us', items: [ { label: 'Discord', href: 'https://discord.gg/vjRPMhFaBA', }, { label: 'Support', href: 'https://kinsta.com/kinsta-support/', }, { label: 'Twitter', href: 'https://twitter.com/kinsta', }, ], }, { title: 'More', items: [ { label: 'Application Hosting', href: 'https://kinsta.com/application-hosting/', }, { label: 'Database Hosting', href: 'https://kinsta.com/database-hosting/', }, { label: 'WordPress Hosting', href: 'https://kinsta.com/wordpress-hosting/', }, { label: 'DevKinsta', href: 'https://kinsta.com/devkinsta/', }, ], }, ], };

顏色和 CSS

Docusaurus 的經典預設使用 Infima CSS 框架。 考慮到這一點，Docusaurus 的創建者製作了一個非常有用的網絡工具來幫助您更改顏色和其他 CSS 元素和聲明。

在頁面上輸入首選項後，該工具將在幾秒鐘內生成一個custom.css文件，其中包含一套可愛的互補色調。 然後，您可以將這個新的 CSS 文件複製到項目的/src/css目錄中以供參考。

文檔

您新網站上的所有文檔都存儲在/docs文件夾中。 當然，您可以在docusaurus.config.js中更改文件夾名稱。

只需在您的文本或 HTML 編輯器中創建降價文件並將它們放入該文件夾中。 每個文件應如下所示：

 --- id: the-id title: Title --- # Rest of the document

根據 ID，Docusaurus 為該子文件夾中的文章構建 URL： yourdomain.com/docs/{id}

如果想將文檔分成不同的邏輯部分，我們還可以創建子文件夾。 但是，我們需要為這些子目錄做一些額外的工作才能按照我們期望的方式運行。

假設我們創建了一個名為“Starters”的新文檔文件夾。 如果我們隨後刷新主頁並單擊自動添加到側邊欄的新“Starters”鏈接，我們將收到錯誤消息——因為我們的新文件夾中還沒有索引頁面。

解決此問題的最簡單方法是創建一個_category_.json文件，該文件將生成存儲在該文件夾中的所有頁面的索引。 您只需要添加以下代碼：

 { "label": "Starters", "position": 2, "link": { "type": "generated-index", "description": "All Kinsta Starters" }, };

如您所見，側邊欄會重新生成以匹配您的文件結構。 那是因為sidebar.js文件包含這個tutorialSidebar : [{type: 'autogenerated', dirName: '.'}],

如果你喜歡自己處理這個，你可以把它改成這樣：

 tutorialSidebar: [ 'intro', 'hello', { type: 'category', label: 'Tutorial', items: ['tutorial-basics/create-a-document'], }, ],

博客

Docusaurus 包括一個靈活的博客模塊。 在您的主要網站旁邊放置一個博客對於通知您的用戶群您的項目中發生的變化或以更新日誌的形式繼續運行項目註釋非常有用。

每個帖子都包含一個 frontmatter 部分，如下所示：

 --- slug: docusaurus-starter title: Docusaurus Starter authors: palmiak tags: [starters, docusaurus] ---

……當然還有內容本身。 它還有一個非常有用的<!--truncate-->標籤，有助於限制在所有帖子列表中顯示的帖子摘要。

為學分創建一個authors.yml文件也是一個好主意。 該文件如下所示：

 palmiak: name: Maciek Palmowski title: DevRel url: https://github.com/palmiak image_url: https://github.com/palmiak.png

多虧了這個文件，您可以將所有作者的數據集中在一個地方以便於參考。

如何在 Kinsta 部署您的 Docusaurus 網站

在 WordPress 網站、獨立應用程序和數據庫之上，Kinsta 可以託管靜態網站。

這意味著它非常適合您的 Docusaurs 網站——以及管理您所有的網絡項目——直接從您的 MyKinsta 儀表板。

部署應用程序後，您將能夠查看應用程序的實時和歷史分析，其中包括：

• 帶寬使用
• 構建時間
• 運行
• CPU使用率
• 內存使用情況

從開始到結束，通過 MyKinsta 的部署過程只需要幾分鐘。

讓我們開始吧！

先決條件：配置您的 Docusaurus 項目

要在 Kinsta 的應用程序託管平台上託管您的 Docusaurus 項目，您需要：

1. 在package.json文件中包含一個名稱字段。 （這可以是任何內容，不會影響您的部署。）
2. 在package.json文件中包含構建腳本。 （你的 Docusaurus 項目應該已經包含了這個。）
3. 安裝 serve npm 包並將啟動腳本設置為 serve build。

一旦勾選了這些，您就可以繼續實際部署您的站點。

部署您的 Docusaurus 項目

按照這些簡單的步驟連接到您的 GitHub 帳戶並啟動您的 Docusaurus 站點：

1. 登錄到您的 MyKinsta 帳戶，然後從左側菜單導航到“應用程序”選項卡。
2. 單擊藍色的添加服務按鈕並從下拉列表中選擇應用程序。

   

3. 如果您尚未通過 MyKinsta 連接到您的 GitHub 帳戶，您將看到一個鼓勵您這樣做的模式。 單擊繼續使用 GitHub按鈕繼續。

   

4. 將打開一個新窗口，請求您授權 Kinsta 訪問和管理您的 GitHub 資源。 確保您登錄到正確的 GitHub 帳戶，然後單擊底部附近的綠色授權 Kinsta按鈕。

   

5. 您現在已進入 GitHub 集成嚮導。 這是部署站點之前的最後一步。 仔細考慮顯示的字段並根據您的 GitHub 配置和項目要求填寫它們。 如果您的存儲庫中有 Dockerfile，則可以使用它來設置容器映像； 否則，Kinsta 會自動為您設置一個容器鏡像。 請注意，您可能需要先編輯 GitHub 權限才能繼續，特別是如果這是您第一次通過 Kinsta 進行部署。

   

   您可以選擇是授予 Kinsta 訪問所有存儲庫的權限，還是僅授予特定存儲庫的訪問權限。 可以隨時從 GitHub 帳戶的應用程序設置中調整這些權限。

   

6. 在您做出選擇並確認您的選擇後，您將看到您的部署詳細信息，以及更改設置或重新部署的選項。

   

   您還可以在這裡看到部署期間發生的任何錯誤，以及導致故障的詳細信息，以便您輕鬆解決問題。 如果您發現自己難以解決問題，可以在 Kinsta 的文檔中找到有關推出錯誤的其他指導。

   

如果您到目前為止沒有錯誤，那麼恭喜您 - 您剛剛通過 Kinsta 成功部署了 Docusaurus 網站！ 完成嚮導後，您的應用程序（即您的靜態站點）就可用了。 您可以在應用程序的 URL 中查看它，通常是https:// your-docusaurus-site .kinsta.app 。

這是我們在 Kinsta 上的示例網站的第一眼：

概括

憑藉其驚人的強大功能、友好的設計、直觀的導航和對內容的關注，不難看出為什麼 Docusaurus 被認為是任何希望輕鬆部署和維護流線型、組織良好的靜態文檔站點和/或博客。 切換您的 Web 開發遊戲！ 告別笨重的 CMS，迎接 Docusaurus - 一個簡單的靜態站點生成器，它正在改變開發遊戲。 在這裡查看️ 點擊推文

在您的站點中填滿訪問者會重視的內容後，您將開始注意到可以派上用場的其他內置功能。 例如，Docusaurus 的搜索引擎優化功能非常適合幫助您在更廣泛的受眾群體中獲得更高的知名度，同時您還可以使用其他技術來提高 SEO 排名。

你用 Docusaurus 做過什麼嗎？ 在下面的評論部分與我們分享您的項目和經驗。