【學習筆記】如何使用 Docusaurus & React 快速架設靜態網站

前言

這是繼 HackMD 和 Hexo 之後，找到的下一個據點，打從第一眼看到 docs 版面配置，就在心底讚嘆：「這不就是我一直想做的功能嗎！」

能夠快速把過去所學的知識打包起來，並以有效率的方式整理，適用於內容驅動型的網站，並且內建支援夜間模式轉換功能。此外，使用的還是快被自己遺忘 React.js 語法，簡直一石多鳥，相見恨晚。

於是乎，這篇筆記就誕生了。

主要會介紹如何使用 Docusaurus 搭配 React 快速架設個人網站。文章可分為下列幾個部分：

前言
什麼是 Docusaurus？
- 為什麼選擇 Docusaurus？
環境建置
專案架構
- Docusaurus 設定檔
- 建立模板頁面
- 支援 TypeScript 語法

什麼是 Docusaurus？

Document（文件）+ saurus（恐龍）= Docusaurus
一直覺得這名字很難記，透過拆字希望能幫助記憶:3

Docusaurus 是由 Facebook 推出的開源靜態網站生成工具，以 React 技術構建，提供快速建置以文檔內容為核心的網站。

為什麼選擇 Docusaurus？

開頭有提到 Docusaurus 幾項特點，再參照官網說明後整理如下：

支援 Markdown 擴充格式 MDX
可在文檔中編寫 JSX 語法，並渲染為 React 的 component
支援 i18n，可使用 Crowdin 將文檔翻譯成 70 多種語言
文檔版本控制
algolia 搜索功能
實際應用範例：Create React App、React Native、Gulp 等，更多可參考官網列表

環境建置

詳細教學可參考官網連結。

步驟如下：

初始化專案

$ npx @docusaurus/init@latest init my-website classic
$ npx docusaurus --version

切換路徑至剛才建立好的專案底下

$ cd my-blog

運行專案

$ npm run start

即可在 http://localhost:3000/ 看到專案預設頁面如下，自動建立了首頁和 Tutorial、Blog 兩個文檔頁面：

在部署前，需將網站資料打包到 /build 資料夾中，即可在 GitHub 等平台部署靜態網頁

$ npm run build

專案架構

以下是官網提供的範例架構：

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           // docs 側邊欄配置
└── yarn.lock

blog
- 預設名稱：blog-examples-from-docusaurus)
- 路由：/blog
- 存放 blog markdown 檔，也就是部落格文章
- 文檔名稱需符合 yyyy-mm-dd-file-name.md
docs
- 預設名稱：docs-examples-from-docusaurus
- 路由：/docs
- 存放 markdown 文檔
src
- css
  - custom.css 用來自定義樣式
- pages
  - 預設的 index.js 包含 Home Component
  - 可用來新增頁面和對應路由，參考官網教學
static
- 存放靜態資源，例如圖片檔
docusaurus.config.js
- 網站配置設定檔
- 等同於 Docusaurus v1 中的 siteConfig.js 檔
sidebars.js
- 自定義 docs 側邊欄

接著開啟剛才建置完成的專案目錄，docs 資料夾內的文檔對應頁面如下：

Docusaurus 網站相關配置

其中 docusaurus.config.js 這個檔案，主要用來設定框架配置：

Required fields 必要配置

module.exports = {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  baseUrl: '/',
};

Optional fields 自選配置

網站圖示、網站標語

module.exports = {
  favicon: '/img/favicon.ico',
  tagline:
    'Docusaurus makes it easy to maintain Open Source documentation websites.',
};

i18n 多國語系

module.exports = {
  i18n: {
    defaultLocale: 'zh-TW',     // 預設語系
    locales: ['en', 'zh-TW'],   // 語系配置
    localeConfigs: {
      en: {
        label: 'English',
        direction: 'ltr',       // 閱讀方向為左到右
      },
      'zh-TW': {
        label: '繁體中文（台灣）',
        direction: 'ltr',
      },
    },
  },
};

GitHub 用戶、專案、主機名稱，用於專案部署

module.exports = {
  // Docusaurus' organization is facebook
  organizationName: 'facebook',
  projectName: 'docusaurus',
 githubHost: 'github.com',
};

自定義主題外觀：例如 navbar、footer

module.exports = {
  themeConfig: {              // 自定義主題配置
    hideableSidebar: false,   // 側邊欄可否收起展開
    colorMode: {              // 深淺色配置
      defaultMode: 'light',
      disableSwitch: false,
      respectPrefersColorScheme: true,
      switchConfig: {
        darkIcon: '🌙',
        lightIcon: '\u2600',
        // React inline style object
        // see https://reactjs.org/docs/dom-elements.html#style
        darkIconStyle: {
          marginLeft: '2px',
        },
        lightIconStyle: {
          marginLeft: '1px',
        },
      },
    },
    navbar: {                 // 導覽列
      title: 'Site Title',    // 網站標題
      logo: {
        alt: 'Site Logo',
        src: 'img/logo.svg',
      },
      items: [                // 導覽列 => docs, blog...等
        {
          to: 'docs/docusaurus.config.js',
          activeBasePath: 'docs',
          label: 'docusaurus.config.js',
          position: 'left',
        },
        // ... other links
      ],
    },
    footer: {               // 底部區塊配置
      style: 'dark',
      links: [
        {
          title: 'Docs',
          items: [
            {
              label: 'Docs',
              to: 'docs/doc1',
            },
          ],
        },
        // ... other links
      ],
      logo: {
        alt: 'Facebook Open Source Logo',
        src: 'https://docusaurus.io/img/oss_logo.png',
      },
      copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // You can also put own HTML here
    },
  },
};

plugins 插件

module.exports = {
  plugins: [],
};

themes 主題

module.exports = {
  themes: [
    // 互動式程式碼編輯器
    require.resolve('@docusaurus/theme-live-codeblock'),
    // 搜尋功能
    require.resolve('@docusaurus/theme-search-algolia'),
    // 程式碼高亮顯示
    require.resolve('@docusaurus/theme-classic'),
  ],
};

customFields：因 Docusaurus 不允許 docusaurus.config.js 檔案中存在未知欄位，可在此區塊自定義欄位

module.exports = {
  customFields: {
    admin: 'endi',
    superman: 'lol',
  },
};

scripts：<script> 經過編譯後會插入 HTML 的 <head>

module.exports = {
  scripts: [
    // String format.
    'https://docusaurus.io/script.js',
    // Object format.
    {
      src:
        'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js',
      async: true,    // 是否同步
    },
  ],
};

建立模板頁面

---
id: intro
title: 啦啦啦
---

這是我的 *新文件内容

markdown 內容
將你的文檔以 .md 文件的形式添加到 /docs 文件夾中，並確保每個文件都有正確的 header
最簡單的標題如下
id 是連結名稱，例如 docs/intro.html
title 是瀏覽器頁面的標題

支援 TypeScript 語法

在初始化專案的語法最後，加上 --typescript：

npx @docusaurus/init@latest init my-website classic --typescript

接著安裝 typescript 需要的相關套件：

npm install --save-dev typescript @docusaurus/module-type-aliases @types/react @types/react-router-dom @types/react-helmet @tsconfig/docusaurus

在位於根目錄的 tsconfig.json 檔案中，新增以下內容：

{
  "extends": "@tsconfig/docusaurus/tsconfig.json",
  "include": ["src/"]
}

部署

詳細可參考官網教學。

過去在部署 Hexo Blog 時，就曾寫過關於如何將專案部署到 GitHub 的筆記，這次嘗試在 Vercel 或 Netlify 平台進行部署，以及透過設定 DNS 紀錄，達成自動轉址功能，搜尋相關設定網路上其實也有不少大神分享，因此就不再作贅述。

最後，這是架設好的 docusaurus2 個人網站，沒想到很久前一直卡關的 DNS 設定，這次竟然蠻順利就達成目的了！之後會陸續把過去寫的學習筆記整理過，再彙整到小恐龍上，期許自己能夠循序漸進，每天都比昨天的自己更進步一些。

參考資料

Docusaurus 2 介紹與使用
10 大靜態網站生成工具
基于 React 的 CMS 框架对比：Docusaurus vs. Gatsby
Docusaurus 配置 GitHub Action 自动发布
[部落格改版學DevOps][08]netlify 超佛心的靜態網站hosting服務 - 不只做hosting還有更多