Docusaurus v3 初始配置

最近想把个人播客做一个升级，发现从 Docusaurus_v2 升级到 Docusaurus_v3 有很多各种各样的配置问题。

于是我决定重新初始化 Docusaurus_v3 的项目，并在此文记录整个过程。

创建新项目

npx create-docusaurus@latest xiaokaup-v3 classic --typescript

整合 Tailwindcss (此方法会导致 UI 出问题, @TODO: fix it)

Docusaurus: A Guide to Seamless Integration with Tailwind CSS: https://medium.com/@bargadyahmed/docusaurus-a-guide-to-seamless-integration-with-tailwind-css-dd202211caac

安装依赖

在实际项目中，这三个工具通常一起使用：PostCSS 作为处理器，运行 Autoprefixer 和 TailwindCSS 插件，形成完整的 CSS 处理流程。

yarn add -D tailwindcss postcss autoprefixer

使用 tailwindcss 自动化初始设置

注意版本，请使用 tailwindcss@^3.4.1 之类的版本, tailwindcss@^4.0.0 不太能成功运行 init 指令。

npx tailwindcss init

创建 tailwind.config.js

个人做的设置，可根据自己的需要做修改。

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  corePlugins: {},
  content: [],
  theme: {
    extend: {},
  },
  plugins: [],
};

创建 ./plugins/tailwind-config.cjs

tailwind-config.cjs

function tailwindPlugin(context, options) {
  return {
    name: "tailwind-plugin",
    configurePostCss(postcssOptions) {
      postcssOptions.plugins = [
        require("postcss-import"),
        require("tailwindcss"),
        require("autoprefixer"),
      ];
      return postcssOptions;
    },
  };
}

module.exports = tailwindPlugin;

升级 docusaurus.config.ts 设置

docusaurus.config.ts

import tailwindPlugin from "./plugins/tailwind-config.cjs";
// Others

const config = {
  title: "小卡 up 养成计划",
  tagline: "Hi 这里是喜欢研究效率工具和思维方式的小卡～",
  // Others
  plugins: [tailwindPlugin],
};

Add tailwindcss into ./src/css/custom.css

@tailwind base;
@tailwind components;
@tailwind utilities;

/* Others */

/* Fix UI issues from Tailwindcss */
img,
svg,
video,
canvas,
audio,
iframe,
embed,
object {
  display: unset;
}

验证是否成功整合 Tailwindcss

整合 mermaid 画图

theme-mermaid: https://docusaurus.io/docs/next/api/themes/@docusaurus/theme-mermaid

安装

yarn add @docusaurus/theme-mermaid

设置

docusaurus.config.ts

const config = {
  // Others

  themes: ["@docusaurus/theme-mermaid"],
  markdown: {
    mermaid: true,
  },

  // Others
};

启用数学方程式 (math equations)

Math Equations: https://docusaurus.io/docs/markdown-features/math-equations

安装

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

设置

docusaurus.config.ts

// Others

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


const config = {
  // Others

  presets: [
    // Others

    [
      "classic",
      // Others

      docs: {
        // Others
        remarkPlugins: [remarkMath],
        rehypePlugins: [rehypeKatex]
        // Others
      },
      blog: {
        // Others
        remarkPlugins: [remarkMath],
        rehypePlugins: [rehypeKatex]
        // Others
      }

      // Others
    ]

    // Others
  ]

  // Others

  stylesheets: [
    {
      href: 'https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css',
      type: 'text/css',
      integrity:
        'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
      crossorigin: 'anonymous',
    },
  ],

  // Others
};

结果

$$
I = \int_0^{2\pi} \sin(x)\,dx
$$

$$I = \int_0^{2\pi} \sin(x)\,dx$$

整合搜索功能

安装

yarn add @easyops-cn/docusaurus-search-local

设置

docusaurus.config.ts

const config = {
  // Others

  themes: [
    "@docusaurus/theme-mermaid",
    [
      require.resolve("@easyops-cn/docusaurus-search-local"),
      /** @type {import("@easyops-cn/docusaurus-search-local").PluginOptions} */
      {
        // ... Your options.

        blogDir: ["blog"],
        // blogDir: ["blog", "blog-weekly"], // @Feature: multiple-blog

        // `hashed` is recommended as long-term-cache of index file is possible.
        hashed: true,

        // For Docs using Chinese, it is recomended to set:
        language: ["zh", "en"],
        highlightSearchTermsOnTargetPage: true,

        // If you're using `noIndex: true`, set `forceIgnoreNoIndex` to enable local index:
        // forceIgnoreNoIndex: true,
      },
    ],
  ],

  // Others
};

其他依赖

这些依赖是我在 md 文件中需要使用的，所以需要安装，可根据个人需要选择性安装。

安装

yarn add @docusaurus/plugin-ideal-image react-player docusaurus-plugin-clarity docusaurus-plugin-image-zoom react-player chart.js chartjs-plugin-datalabels sass docusaurus-plugin-sass

设置

docusaurus.config.ts

const config = {
  // Others

  themeConfig: {
    // Others

    zoom: {
      selector: ".markdown :not(em) > img",
      background: {
        light: "rgb(255, 255, 255)",
        dark: "rgb(50, 50, 50)",
      },
      config: {
        // options you can specify via https://github.com/francoischalifour/medium-zoom#usage
      },
    },
    clarity: {
      ID: "h*********", // 填写你自己的 clarity id
    },

    // Others
  }

  plugins: [
    [
      "@docusaurus/plugin-ideal-image",
      {
        quality: 70,
        max: 1030, // max resized image's size.
        min: 640, // min resized image's size. if original is lower, use that size.
        steps: 2, // the max number of images generated between min and max (inclusive)
        disableInDev: false,
      },
    ],
    "docusaurus-plugin-image-zoom",
    "docusaurus-plugin-clarity",
    "docusaurus-plugin-sass",
    // Others
  ],

  // Others
};