技術部落格初體驗：Docusaurus設定好複雜？

2024年10月11日 · 閱讀時間約 5 分鐘

Back End Engineer

剛開始時，整個安裝過程其實並不複雜，尤其是對於有一定開發經驗的人來說，跟著步驟走幾乎沒有障礙。不過，當我開始配置我的部落格主題和個性化內容時，就發現了一些挑戰。

自訂配置

在 docusaurus.config.js 文件中，你可以自訂網站的各項配置，包括標題、主題、插件等。雖然這些配置項比較清晰，但在初期對我來說還是有些困惑。特別是在選擇主題和插件時，我花了一些時間才找到適合我需求的配置。

設定我的主題：

    title: 'Chao-En Huang', // 這邊是你封面的標題
    tagline: // 這邊是你封面的副標
    '這裡整理了我在軟體技術領域的學習心得與實踐經驗，分享我的見解與解決問題的方法。',
    favicon: 'img/favicon.ico', // 這是你網頁的icon
    url: 'https://koteruon.github.io', // 這是首頁的URL

設定部屬的位置：因為我部屬在github page上面，以下是我的示範

    organizationName: 'koteruon', // github的使用者名稱
    projectName: 'koteruon.github.io', // 靜態網站的domain name
    trailingSlash: false, // 網址後面需不需要/
    deploymentBranch: 'main', // 部版的branch
    onBrokenLinks: 'throw',
    onBrokenMarkdownLinks: 'warn',

設定語系：這邊我選擇使用中文繁體的語系

    i18n: { // 設定為台灣的語系
        defaultLocale: 'zh-Hant',
        locales: ['zh-Hant'],
    },

設置基礎設定：調整blogSidebarCount為10增加部落格顯示數量，如果有需要使用mdx，然後**/*表示所有目錄底下所有的md和mdx檔案都會被解析。

presets: [
    [
        'classic', // 經典的配置(不用動)
        {
            docs: {
                sidebarPath: './sidebars.ts', // 設定旁邊側邊的目錄設定的路徑(不用動)
                // 增加 remarkMath and rehypeKatex 的套件，下一個步驟會教
                remarkPlugins: [remarkMath],
                rehypePlugins: [rehypeKatex],
            },
            blog: {
                blogSidebarCount: 10, // 部落格顯示的數量(可以調整為10)
                showReadingTime: true,
                routeBasePath: '/blog', // 部落格的資料夾路徑(不用動)
                include: ['**/*.{md,mdx}'], // 為了支持md和mdx的解析
                // (**/*代表BasePath底下所有路徑的md和mdx檔案)
                feedOptions: {
                    type: ['rss', 'atom'],
                    xslt: true,
                },
                onInlineTags: 'warn',
                onInlineAuthors: 'warn',
                onUntruncatedBlogPosts: 'warn',
            },
            theme: {
                customCss: './src/css/custom.css',
            },
        } satisfies Preset.Options,
    ],
],

增加數學表達式(如果需要才要用)：執行下面的程式後，在docusaurus.config.js的最上面增加import，並且設定Plugins。

yarn add remark-math@6 rehype-katex@7

import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

presets: [
    [
        'classic',
        {
            docs: {
                path: 'docs',
                remarkPlugins: [remarkMath],
                rehypePlugins: [rehypeKatex],
            },
        },
    ],
  ],

stylesheets: [ // 增加katex需要的css樣式
    {
        href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css',
        type: 'text/css',
        integrity:
        'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
        crossorigin: 'anonymous',
    },
]

數學公式範例：

增加右上角的搜尋功能：他可以搜尋所有blog和docs裡面的文章，

plugins: [
    [
      '@easyops-cn/docusaurus-search-local',
      {
        hashed: true,
        language: ['en', 'zh'], // 增加zh增加中文搜尋
        docsRouteBasePath: '/',
      },
    ],
  ],

上下導覽列設定：這個設定比較複雜，我將在下一篇技術部落格初體驗：Docusaurus設定真的很複雜啊(佈置篇)

結語

總的來說，雖然 Docusaurus 的設定過程在初期看似複雜，但隨著我慢慢理解每一項配置後，發現其實這一切並沒有想像中那麼困難。每一步的設定都有其意義，透過官方文檔的指導和實際操作的體驗，逐漸能夠掌握這個框架的運作方式。這讓我感受到，搭建自己的技術部落格並不是一件難事，反而充滿了樂趣和挑戰。

自訂配置​

結語​

自訂配置

結語