技術部落格初體驗：Docusaurus設定真的很複雜啊(佈置篇)

2024年10月12日 · 閱讀時間約 6 分鐘

Back End Engineer

隨著自訂的增加，佈景的設定也越來越多，docusaurus.confg.ts 太長了怎麼辦！？每次要找東西都好辛苦~

自訂配置

首先我們將 themeConfig 從 docusaurus.config 中抽離出來，另外放到專案目錄下的 config 底下

docusaurus.confg.ts
import themeConfig from './config/themeConfig';

const config: Config = {
  // Theme configurations
  themeConfig,
};

config/themeConfig.ts
// 引入相關需要使用的套件
import type * as Preset from '@docusaurus/preset-classic';
import { themes as prismThemes } from 'prism-react-renderer';

const themeConfig = {} satisfies Preset.ThemeConfig;

// 將設定export出去
export default themeConfig;

將佈景的設定放置於 config 底下，並開始制定相關佈景，首先更換自己的 image 和 favicon

config/themeConfig.ts
const themeConfig = {
  // 可以更換成自己想要的帳片和icon，在網站縮圖或轉發連結或網頁縮圖都會使用到
  image: 'images/icon/chao_en_huang_icon.png',
  favicon: 'images/icon/favicon.ico',
};

Docs，在 docs 的分業中，有沒有要自動縮合

config/themeConfig.ts
const themeConfig = {
  // Docs
  docs: {
    sidebar: {
      autoCollapseCategories: true,
    },
  },
};

Navbar，這裡可以設定網頁上面的分頁標籤，設定名字、Logo，並設定要有那些分頁

config/themeConfig.ts
const themeConfig = {
  // Navbar
  navbar: {
    title: 'Chao-En',
    logo: {
      alt: 'My Site Logo',
      src: 'images/icon/apple-touch-icon.png',
    },
    // hideOnScroll: true,
    items: [
      {
        // 設定自己想要跳轉的頁面
        to: '/about-me',
        label: 'About Me',
        position: 'left',
      },
      {
        // 設定要是像doc樣子的sidebar
        type: 'docSidebar',
        sidebarId: 'notesSidebar', //在sidebars.ts中定義，如何生成sidebar
        position: 'left',
        label: 'Notes',
      },
      {
        // 設定要是像doc樣子的sidebar
        type: 'docSidebar',
        sidebarId: 'researchSidebar', //在sidebars.ts中定義，如何生成sidebar
        position: 'left',
        label: 'Research',
      },
      {
        // 設定部落格的分頁
        to: '/blog',
        label: 'Blog',
        position: 'left',
      },
      {
        // 增加github的連結在最右邊
        href: 'https://github.com/koteruon',
        label: 'GitHub',
        position: 'right',
      },
    ],
  },
};

設定 sidebars 如何生成，並在 docusaurus.config.ts 中增加位置，同時也需要設定 blog 生成的位置

docusaurus.confg.ts
const config: Config = {
  presets: [
    [
      'classic',
      {
        docs: {
          // 生成sidebars的檔案位置
          sidebarPath: './sidebars.ts',
          // Add remarkMath and rehypeKatex plugins.
          remarkPlugins: [remarkMath],
          rehypePlugins: [rehypeKatex],
        },
        blog: {
          blogSidebarCount: 10,
          showReadingTime: true,
          // 部落格的網址
          routeBasePath: '/blog',
          include: ['**/*.{md,mdx}'],
          feedOptions: {
            type: ['rss', 'atom'],
            xslt: true,
          },
          // Useful options to enforce blogging best practices
          onInlineTags: 'warn',
          onInlineAuthors: 'warn',
          onUntruncatedBlogPosts: 'warn',
        },
        theme: {
          // 自訂global的css
          customCss: './src/css/custom.css',
        },
      } satisfies Preset.Options,
    ],
  ],
};

sidebars.ts
import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';

const sidebars: SidebarsConfig = {
  // 因為有兩個分頁，且希望自動生成，在markdown中再決定分頁順序和網址，比較不會寫死
  notesSidebar: [{ type: 'autogenerated', dirName: 'notes' }],
  researchSidebar: [{ type: 'autogenerated', dirName: 'research' }],
};

export default sidebars;

CodeBlock，自訂在 markdown 的 codeblock 可以 highlight 不同的顏色

// 加上highlight-next-line
const highlight-next-line;

// 加上This-will-error
const This-will-error;

// 加上This-will-accept
const This-will-accept;

config/themeConfig.ts
const themeConfig = {
  // CodeBlock
  prism: {
    // 根據自己需要的語言而增加
    additionalLanguages: ['powershell', 'java'],
    theme: prismThemes.github,
    darkTheme: prismThemes.dracula,
    magicComments: [
      // Remember to extend the default highlight class name as well!
      {
        className: 'theme-code-block-highlighted-line',
        line: 'highlight-next-line',
        block: { start: 'highlight-start', end: 'highlight-end' },
      },
      // 增加自己喜歡的highlight名稱
      {
        className: 'code-block-error-line', // css的名稱
        line: 'This-will-error', // markdown中使用它的名稱
      },
      {
        className: 'code-block-accept-line',
        line: 'This-will-accept',
      },
    ],
  },
};

src\css\custom.css
/* Styles for highlighting error lines in code blocks */
.code-block-error-line {
  background-color: #ff000020;
  display: block;
  margin: 0 calc(-1 * var(--ifm-pre-padding));
  padding: 0 var(--ifm-pre-padding);
  border-left: 3px solid #ff000080;
}

/* Styles for highlighting accept lines in code blocks */
.code-block-accept-line {
  background-color: #00ff0020;
  display: block;
  margin: 0 calc(-1 * var(--ifm-pre-padding));
  padding: 0 var(--ifm-pre-padding);
  border-left: 3px solid #00ff0080;
}

Footer，設定頁尾的樣式和分類，可以使用 to 跳轉到 domain 一樣的其他網址、或是 href 到其他網址，或是直接增加 html block，最後 copy right 使用自動生成年分，未來就不用手動改。

config/themeConfig.ts
const themeConfig = {
  // Footer
  footer: {
    // style: 'dark', // 可以設定是否要是深色佈景
    // 可以設定有多少個欄位需要而設定
    links: [
      {
        title: 'This Website',
        items: [
          {
            label: 'Notes', // 顯示名稱
            to: '/docs', // 點選跳轉的網址
          },
          {
            label: 'Research',
            to: '/docs/research',
          },
          {
            label: 'Blog',
            to: '/blog',
          },
        ],
      },
      {
        title: 'Community',
        items: [
          {
            label: 'GitHub',
            href: 'https://github.com/koteruon',
          },
          {
            label: '104',
            href: 'https://pda.104.com.tw/profile/preview?vno=75wef33ky',
          },
          {
            label: 'Linkedin',
            href: 'https://www.linkedin.com/in/%E7%85%A7%E6%81%A9-%E9%BB%83-93511b25b/',
          },
        ],
      },
      {
        title: 'Acknowledgement',
        items: [
          {
            html: `
              <p>
              illustrations by <a href="https://storyset.com/web">Storyset</a>
              </p>
              `,
          },
        ],
      },
    ],
    copyright: `Copyright © ${new Date().getFullYear()} Chao-En Huang. Built with Docusaurus.`,
  },
};

覺得部落格的字體太大了，自訂 css 來挑整字體大小

src\css\custom.css
/* Reduce title size in blog list and blog post pages */
.blog-post-page h1[class*='title'],
.blog-list-page h2[class*='title'],
.blog-tags-post-list-page h2[class*='title'] {
  font-size: 2.5rem;
}

自訂配置​

自訂配置