跳至主要内容

[Docusaurus] 自訂你的 Docusaurus

docs 分版​

若要把 docs 內部的文件分成兩個以上的 page，需要手動設定 sidebar.ts：

以本站為例
const sidebars: SidebarsConfig = {
  notes: [
    {
      type: 'category',
      label: '筆記',
      link: {
        type: 'doc',
        id: 'notes/index', // 對應 /docs/notes/index.mdx
      },
      items: [
        {
          type: 'autogenerated',
          dirName: 'notes',
        },
      ],
    },
  ],
  series: [
    {
      type: 'category',
      label: '系列文章',
      link: {
        type: 'doc',
        id: 'series/index', // 對應 /docs/series/index.mdx
      },
      items: [
        {
          type: 'autogenerated',
          dirName: 'series',
        },
      ],
    },
  ],
};

接下來至 docusaurus.config.js 的 presets 與 themeConfig 做相對應設定即可。

新增網頁搜索​

大部人比較喜歡使用 algolia，但我個人沒有到很愛用它，所以我是換成 @easyops-cn/docusaurus-search-local。

  1. 先安裝插件
npm install --save @easyops-cn/docusaurus-search-local
  1. 前往 docusaurus.config.js 添加下列內容：
const config = {
  themes: [
    [
      "@easyops-cn/docusaurus-search-local",
      {
        hashed: true,
        language: ["en", "zh"],
        highlightSearchTermsOnTargetPage: true,
        explicitSearchResultPath: true,
      },
    ],
  ],
}
  1. npm run build 即可搜索。

Mermaid 圖表​

基本上 Docusaurus 是個支援使用 markdown 產生網頁內容的框架，了不起最多支援 MDX。所以想在 MD 或 MDX 裡使用圖表會需要額外支援，Mermaid 就是一個好選擇。

  1. 先安裝 @docusaurus/theme-mermaid
npm install --save @docusaurus/theme-mermaid
  1. 設定 docusaurus.config.ts
export default {
  markdown: {
    mermaid: true,
  },
  themes: ['@docusaurus/theme-mermaid'],
};
提示

安裝 VScode Mermaid 插件輔助開發。

Code Block​

Docusaurus 的 code block 其實預設只支援部分語言，對於像 C# 等 docusaurus 本身沒預設的語言，寫在 code block 裡會因為 docusaurus 不知道它是誰而無法正確高亮顯示。
要在 docusaurus 中擴充 code block 支援特定語言可以參考 prismjs 程式碼區塊支援語言表，然後在 docusaurus.config.js 的 themeConfig 中新增 prism 設定：

prism: {
  theme: prismThemes.github,
  darkTheme: prismThemes.dracula,
  additionalLanguages: ['csharp', 'dart', 'powershell', 'scss']
}

Google Analytics​

  1. 先安裝 @docusaurus/plugin-google-gtag。但如果是使用 classic preset 的話，可以直接跳 2.。
npm install --save @docusaurus/plugin-google-gtag
  1. 去 Google Analytics 申辦一個評估 ID。
  2. 在 presets 設定中新增 gtag 設定：
gtag: {
  trackingID: 'G-XXXXXXXXXX', // 這是你的 Google Analytics 評估 ID
  anonymizeIP: true,
}

giscus 留言板​

注意

我在 2025 更新新版部落格後將留言板移除了，理由如下：

  1. 留言板的使用率很低，幾乎沒有留言。
  2. giscus 其實有一種傳統網頁的美...

giscus 的優點是可以在 GitHub 統一管理留言，而且免費無廣告！但對應的缺點是要留言要登入 GitHub 帳號。

  1. 先照 giscus 文件上說的檢查：

    • repo 是否已公開。
    • 是否已在 GitHub 安裝 giscus 應用程式。
    • repo 是否已啟用 Discussions 功能。

  2. 回到 giscus 文件，填入自己 repo 的網址，giscus 會檢查是否滿足上述的條件，都滿足就會開放功能給予選取，之後會自動產生一段 code，大致像這樣：

<script src="https://giscus.app/client.js"
data-repo="[在此輸入儲存庫名稱]"
data-repo-id="[在此輸入儲存庫 ID]"
data-category="[在此輸入分類名稱]"
data-category-id="[在此輸入分類 ID]"
data-mapping="pathname"
data-strict="0"
data-reactions-enabled="1"
data-emit-metadata="0"
data-input-position="bottom"
data-theme="preferred_color_scheme"
data-lang="zh-TW"
crossorigin="anonymous"
async>
</script>
提示

上面的在此輸入...不用真的輸入，在填完 repo 網址後，giscus 會自己產生對應內容。

  1. 回到專案，先安裝 giscus/react 套件：
npm i @giscus/react
  1. 在 components 資料下中新增 comment 資料夾，建立 index.js 檔案：
/components/comment/index.js
import Giscus from "@giscus/react";

export default function Comment(){
  return(
    <div style={{paddingTop: 50}}>
      <Giscus
        id="comments"
        repo="[在此輸入儲存庫名稱]"
        repoId="[在此輸入儲存庫 ID]"
        category="Announcements"
        categoryId="[在此輸入分類 ID]"
        mapping="pathname"
        reactionsEnabled="1"
        emitMetadata="0"
        inputPosition="bottom"
        theme="light"
        lang="zh-TW"
        loading="lazy"
      />
    </div>
  )
}

在部落格文章下添加留言板​

  1. 以指令在 /src/theme 底下產生 BlogPostItem 資料夾。
npm run swizzle @docusaurus/theme-classic BlogPostItem -- --wrap
  1. 將 BlogPostItem 的 index.js 更改如下：
import React from 'react';
import BlogPostItem from '@theme-original/BlogPostItem';
import Comment from '../../components/comment';

export default function BlogPostItemWrapper(props) {
  return (
    <>
      <BlogPostItem {...props} />
      <Comment/>
    </>
  );
}

在 docs 文章下添加留言板​

  1. 以指令在 /src/theme 底下產生 DocItem 資料夾跟 Layout 資料夾。
npm run swizzle @docusaurus/theme-classic DocItem/Layout -- --wrap
  1. 將 /DocItem/Layout 的 index.js 更改如下：
import React from 'react';
import Layout from '@theme-original/DocItem/Layout';
import Comment from '../../../components/comment';

export default function LayoutWrapper(props) {
  return (
    <>
      <Layout {...props} />
      <Comment />
    </>
  );
}

Reference​

  1. 在 Docusaurus 新增搜尋功能