對於輕量級的網站、應用程式和其他小型專案，越來越多的開發人員轉向靜態網站生成器，而不是WordPress或其他內容管理系統（CMS）。靜態網站為建立快速、安全和易於維護的網站和應用程式提供了一種簡單有效的方法。
Docusaurus就是這樣一個靜態網站生成器–它在開發社羣中迅速得到了普及。
在這篇文章中，我們將深入探討使用Docusaurs作為靜態網站生成器的好處，以及為什麼它在開發人員中越來越受歡迎。
什麼是Docusaurus？
Docusaurus是一個流行的靜態網站生成器，它使用React（頂級JavaScript庫之一）作為頁面建立的UI庫。像其他此類生成器一樣，它很容易設定，也很容易修改，而且–最重要的是–它為你提供了你的靜態網站執行所需的一切。
然而，使Docusaurus與眾不同的是，它幫助你建立和管理一個內容發揮關鍵作用的網站。它允許你快速和容易地建立一個完整的網站–完整的部落格功能–從一開始就突出你的內容。
因為內容是Docusaurus的重點，它非常適合建立像維基這樣的文件網站。它還利用了markdown，這對於協作和在git倉庫中的儲存都很理想。更重要的是，它有大量驚人的功能，如i18n、搜尋和自定義主題，我們將在後面詳細討論。
以下是使Docusaurus成為一個可靠選擇的幾個突出特點：
- 使用React構建
- 支援MDX v1
- 支援通過Markdown嵌入React元件
- 文件版本管理
- 與Git、Crowdin和其他翻譯管理器相容，用於文件翻譯和批量或單獨部署
誰在使用Docusaurus？
Docusaurus是由Facebook建立的，所以它目前被整個網路的許多大品牌和公司使用並不奇怪。
以下是目前使用Docusaurus的幾個最大的品牌（隨著Docusaurus的知名度不斷提高，很快會有更多的品牌使用）：
而且每天都有更多的人加入他們的行列。
如何安裝Docusaurus
Docusaurus的安裝非常簡單，只需要幾分鐘時間。在本教程中，我們將建立一個帶有部落格的文件網站，我們將定製網站的外觀。
而這裡是最酷的部分。我們將花不到一個小時的時間來啟動一切。
要求
Docusarus需要Node.js 16.14或更新版本。它是一個平面檔案的SSG，這意味著你不需要一個額外的資料庫。
如果你還沒有Node.js 16.14以上的版本，你將需要先安裝Node.js或升級你目前的版本。然後你就可以進入下面的Docusaurus安裝過程。
我們還將使用這個GitHub倉庫中的Docusaurus樣本網站。你可以使用它，也可以在本教程中使用Docusaurus的乾淨安裝。
安裝過程
要開始Docusaurus的安裝過程，你首先需要執行以下命令：
npx create-docusaurus@latest 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開啟和編輯這些檔案。
讓我們來看看你開箱就有的一些定製選項。
Homepage
你可能迫不及待要做的第一件事是定製預設主頁，以展示你自己的專案。幸運的是，對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 專案。
在我們的例子中，我們要新增一個指向閃電博的連結，將 “Tutorial” 項重新命名為 “Starter documentation”，並新增閃電博的標誌。
下面是我們要做的事情：
navbar: {
title: 'Wbolt starters',
logo: {
alt: 'Wbolt Logo',
src: 'img/wbolt-logo-alpha-purple.png',
},
items: [
{
label: 'Wbolt starters',
to: '/docs/intro',
},
{to: '/blog', label: 'Blog', position: 'left'},
{
href: 'https://github.com/wbolt',
label: 'GitHub',
position: 'right',
},
],
},
頁尾
Docusaurus中的頁尾定製由兩部分組成：頁尾內容本身，以及頁尾連結。
（1）頁尾內容
主要的頁尾內容（不包括連結列表）可以放在你的themeConfig.footer檔案中。這是新增標誌和版權宣告的理想位置。
下面是我們如何修改我們的頁尾配置：
module.exports = {
themeConfig: {
footer: {
logo: {
alt: 'Wbolt Logo',
src: 'img/wbolt-logo.png',
href: 'https://www.wbolt.com',
width: 160,
height: 51,
},
copyright: `Copyright © ${new Date().getFullYear()} Wbolt. Built with Docusaurus.`,
},
},
};
（2）頁尾連結
改變頁尾連結與改變頂部導航欄類似。在docusaurus.config.js中找到 footer 部分，然後編輯，直到它適合你的需要。
下面是我們把 footer 部分改成的樣子：
footer: {
style: 'dark',
links: [
{
title: 'Docs',
items: [
{
label: 'Wbolt starters',
to: '/docs/intro',
},
],
},
{
title: 'Talk with us',
items: [
{
label: 'Discord',
href: 'https://discord.gg/vjRPMhFaBA',
},
{
label: 'Support',
href: 'https://www.wbolt.com/wbolt-support/',
},
{
label: 'Twitter',
href: 'https://twitter.com/wbolt',
},
],
},
{
title: '更多',
items: [
{
label: 'WordPress主題',
href: 'https://www.wbolt.com/themes',
},
{
label: 'WordPress外掛',
href: 'https://www.wbolt.com/plugins',
},
{
label: 'WordPress學院',
href: 'https://www.wbolt.com/learn',
},
{
label: '站長工具',
href: 'https://www.wbolt.com/tools',
},
],
},
],
};
顏色和CSS
Docusaurus的經典預設使用Infima CSS框架。考慮到這一點，Docusaurus的創造者做了一個非常有用的網路工具來幫助你改變顏色和其他CSS元素和宣告。
一旦你在頁面上輸入了你的偏好，這個工具就會在幾秒鐘內生成一個custom.css檔案–完整的補充色調的可愛套件。然後，你可以將這個新的CSS檔案複製到你的專案的/src/css目錄中，以供參考。
Docusaurus官方文件的一部分，展示了他們的自定義CSS工具，其中有一些欄位可以為Docusaurus設計中的每個單獨元素輸入十六進位制程式碼調整。
文件
你新網站上的所有文件都儲存在/docs資料夾中。當然，你可以在docusaurus.config.js中改變這個資料夾的名稱。
只要在你的文字或HTML編輯器中建立markdown檔案，並把它們放到那個資料夾中。每個檔案應該看起來像這樣：
--- id: the-id title: Title --- # Rest of the document
基於這個ID，Docusaurus為該子資料夾中的文章建立了URLs：yourdomain.com/docs/{id}。
如果想把我們的文件分成不同的、有邏輯的部分，我們也可以建立子資料夾。然而，我們需要做一些額外的工作，使這些子目錄以我們期望的方式運作。
假設我們建立了一個名為 “Starters” 的新文件資料夾。如果我們重新整理主頁並點選自動新增到側邊欄的新的 “Starters”連結，我們會得到一個錯誤–因為在我們的新資料夾中還沒有索引頁。
解決這個問題的最簡單方法是建立一個 _category_.json檔案，它將生成儲存在這個資料夾中的所有頁面的索引。你只需要新增以下程式碼：
{
"label": "Starters",
"position": 2,
"link": {
"type": "generated-index",
"description": "All Wbolt Starters"
},
};
正如你所看到的，側邊欄會重新生成，以符合你的檔案結構。這是因為sidebar.js檔案包含這個 tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],。
如果你喜歡自己處理這個問題，你可以直接把它改為這樣的內容：
tutorialSidebar: [
'intro',
'hello',
{
type: 'category',
label: 'Tutorial',
items: ['tutorial-basics/create-a-document'],
},
],
Blog
Docusaurus包括一個靈活的部落格模組。在你的主網站旁邊有一個部落格，對於通知你的使用者群在你的專案中發生的變化是非常有用的，或者作為一種變化日誌的形式保持專案的執行記錄。
每篇文章包括一個前言部分，像這樣：
--- slug: docusaurus-starter title: Docusaurus Starter authors: palmiak tags: [starters, docusaurus] ---
…當然，還有內容本身。它還有一個非常有用的 <!--truncate--> 標籤，這有助於限制所有帖子列表上顯示的帖子摘要。
建立一個author.yml檔案，以獲得信用，也是一個好主意。該檔案看起來像這樣：
palmiak: name: Maciek Palmowski title: DevRel url: https://github.com/palmiak image_url: https://github.com/palmiak.png
由於這個檔案，你將在一個地方擁有所有作者的資料，便於參考。
小結
憑藉其令人驚訝的強大功能、友好的設計、直觀的導航和對內容的關注，不難看出為什麼Docusaurus被認為是任何希望輕鬆部署和維護一個精簡的、組織良好的靜態文件網站和/或部落格的開發者的一個優秀工具。
一旦你用你的訪問者會重視的內容填滿你的網站，你就會開始注意到額外的內建功能，這些功能會很方便。例如，Docusaurus的搜尋引擎優化功能是完美的，可以幫助你通過更廣泛的受眾獲得更好的可見性，同時你還可以通過其他技術來提高SEO排名。
你用Docusaurus建立過什麼嗎？請在下面的評論部分與我們分享你的專案和經驗。
評論留言