个性化增强

整合 Tailwind CSS

由于 Tailwind CSS 现在已经是 v4 了，所以这里以整合 v4 为例，整合 v3 也差不多。

安装依赖

npm install --save-dev tailwindcss postcss @tailwindcss/postcss

添加插件

位置：src/plugins/tailwind-config.js

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

添加配置

docusaurus.config.js 相关配置如下：

import tailwindPlugin from "./src/plugins/tailwind-plugin.js";
const config = {
  //...
  plugins: [tailwindPlugin],
  //...
};

配置 `custom.css`

位置：src/css/custom.css

@import "tailwindcss";

暗色兼容 `TailwindCSS`

修改 custom.css 文件，添加以下代码：

@import "tailwindcss";
+ @custom-variant dark (&:is([data-theme="dark"] *));

参考资料

整合 TailwindCSS Typography 插件

@tailwindcss/typography 插件现在已经支持 tailwindcss@4 了。但是要想在 Docusaurus 中使用，需要做些配置。

安装依赖

npm install --save-dev @tailwindcss/typography

配置 `custom.css`

@import "tailwindcss";
+ @plugin "@tailwindcss/typography";

然后为了让 Typography 插件生效，我们需要给 <article> 标签加上 prose 类名。这需要用到 Docusaurus 的组件覆盖的机制。

覆盖 `<BlogPostItem>` 组件

// src/theme/BlogPostItem/index.js
import React from "react";
import BlogPostItem from "@theme-original/BlogPostItem";
import clsx from "clsx";

export default function BlogPostItemWrapper(props) {
  return (
    <article className={clsx("prose prose-lg max-w-none", props.className)}>
      <BlogPostItem {...props} />
    </article>
  );
}

注 1：默认 Typography 有个奇怪的最大宽度，我们把它禁用掉。注 2：我还对文档做了完全一样的配置，只不过覆盖的组件是：DocItem/index.js。

整合 `shadcn/ui`

shadcn/ui 是一个基于 Tailwind CSS 的组件库。特别的一点是，他不像一般的组件库引用来使用，这个组件库是将所有的代码下载到项目中，可以随意定制。也是最近越来越流行的趋势。Docusaurus 不在其默认支持的框架中，所以要用其手动安装流程。

注意，根据 Docsaurus 是否使用 TypeScript，配置方式会有细微差别，这里以 Javascript 为例。

安装依赖

pnpm add class-variance-authority clsx tailwind-merge lucide-react tw-animate-css

添加 `jsconfig.json`

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]
    }
  }
}

配置全局样式

@import "tailwindcss";
@import "tw-animate-css";

@custom-variant dark (&:is(.dark *));

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0 0);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.97 0 0);
  --secondary-foreground: oklch(0.205 0 0);
  --muted: oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  --accent: oklch(0.97 0 0);
  --accent-foreground: oklch(0.205 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --destructive-foreground: oklch(0.577 0.245 27.325);
  --border: oklch(0.922 0 0);
  --input: oklch(0.922 0 0);
  --ring: oklch(0.708 0 0);
  --chart-1: oklch(0.646 0.222 41.116);
  --chart-2: oklch(0.6 0.118 184.704);
  --chart-3: oklch(0.398 0.07 227.392);
  --chart-4: oklch(0.828 0.189 84.429);
  --chart-5: oklch(0.769 0.188 70.08);
  --radius: 0.625rem;
  --sidebar: oklch(0.985 0 0);
  --sidebar-foreground: oklch(0.145 0 0);
  --sidebar-primary: oklch(0.205 0 0);
  --sidebar-primary-foreground: oklch(0.985 0 0);
  --sidebar-accent: oklch(0.97 0 0);
  --sidebar-accent-foreground: oklch(0.205 0 0);
  --sidebar-border: oklch(0.922 0 0);
  --sidebar-ring: oklch(0.708 0 0);
}

[data-theme="dark"] {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --card: oklch(0.145 0 0);
  --card-foreground: oklch(0.985 0 0);
  --popover: oklch(0.145 0 0);
  --popover-foreground: oklch(0.985 0 0);
  --primary: oklch(0.985 0 0);
  --primary-foreground: oklch(0.205 0 0);
  --secondary: oklch(0.269 0 0);
  --secondary-foreground: oklch(0.985 0 0);
  --muted: oklch(0.269 0 0);
  --muted-foreground: oklch(0.708 0 0);
  --accent: oklch(0.269 0 0);
  --accent-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.396 0.141 25.723);
  --destructive-foreground: oklch(0.637 0.237 25.331);
  --border: oklch(0.269 0 0);
  --input: oklch(0.269 0 0);
  --ring: oklch(0.439 0 0);
  --chart-1: oklch(0.488 0.243 264.376);
  --chart-2: oklch(0.696 0.17 162.48);
  --chart-3: oklch(0.769 0.188 70.08);
  --chart-4: oklch(0.627 0.265 303.9);
  --chart-5: oklch(0.645 0.246 16.439);
  --sidebar: oklch(0.205 0 0);
  --sidebar-foreground: oklch(0.985 0 0);
  --sidebar-primary: oklch(0.488 0.243 264.376);
  --sidebar-primary-foreground: oklch(0.985 0 0);
  --sidebar-accent: oklch(0.269 0 0);
  --sidebar-accent-foreground: oklch(0.985 0 0);
  --sidebar-border: oklch(0.269 0 0);
  --sidebar-ring: oklch(0.439 0 0);
}

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-popover: var(--popover);
  --color-popover-foreground: var(--popover-foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-destructive: var(--destructive);
  --color-destructive-foreground: var(--destructive-foreground);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);
  --color-chart-1: var(--chart-1);
  --color-chart-2: var(--chart-2);
  --color-chart-3: var(--chart-3);
  --color-chart-4: var(--chart-4);
  --color-chart-5: var(--chart-5);
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
  --color-sidebar: var(--sidebar);
  --color-sidebar-foreground: var(--sidebar-foreground);
  --color-sidebar-primary: var(--sidebar-primary);
  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
  --color-sidebar-accent: var(--sidebar-accent);
  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
  --color-sidebar-border: var(--sidebar-border);
  --color-sidebar-ring: var(--sidebar-ring);
}

@layer base {
  * {
    @apply border-border outline-ring/50;
  }
  body {
    @apply bg-background text-foreground;
  }
}

添加助手函数 `lib/utils.js`

import { clsx } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

创建 `components.json` 文件

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": false,
  "tsx": false,
  "tailwind": {
    "config": "",
    "css": "src/css/custom.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}

添加适配插件 `alias-config.js`

由于 Docusaurus 不支持组件里的 @ 符号，所以需要添加一个插件来支持。位置：src/plugins/alias-config.js

const path = require("path");

module.exports = function (context, options) {
  return {
    name: "docusaurus-plugin-alias-config",
    configureWebpack() {
      return {
        resolve: {
          alias: {
            "@": path.resolve(__dirname, ".."),
          },
        },
      };
    },
  };
};

配置 docusaurus.config.js

import aliasConfigPlugin from "./src/plugins/alias-config.js";
const config = {
  plugins: [aliasConfigPlugin],
};

添加 toast 组件

这个在 shadcn/ui 里有变化，之前是 Toast 组件，现在已经启用，改为推荐 sonner 组件了。Sonner 的安装在 Docusaurus 里需要说明一下。

安装依赖

pnpm dlx shadcn@latest add sonner

覆盖默认 Layout

npm run swizzle @docusaurus/theme-classic Layout --javascript --wrap

--javascript：表示使用 JavaScript 而不是 TypeScript
--wrap：表示覆盖默认的 Layout 组件，而不是创建一个新的组件

然后编辑这个 Wrap Layout

位置在：src/theme/Layout/index.js

import React from "react";
import Layout from "@theme-original/Layout";
import { Toaster } from "@/components/ui/sonner";

export default function LayoutWrapper(props) {
  return (
    <>
      <Layout {...props} />
      <Toaster position="top-right" richColors />
    </>
  );
}

根据 Sonner 的文档 https://sonner.emilkowal.ski/, 选择合适的定制参数。剩下的使用就跟其他组件一样了。

import { toast } from "sonner";
toast("Event has been created.");
toast.success("Event has been created.");
toast.error("Event has been created.");
toast.info("Event has been created.");
toast.warning("Event has been created.");

toast("Event has been created", {
  action: {
    label: "Undo",
    onClick: () => console.log("Undo"),
  },
});

const promise = () =>
  new Promise((resolve) => setTimeout(() => resolve({ name: "Sonner" }), 2000));

toast.promise(promise, {
  loading: "Loading...",
  success: (data) => {
    return `${data.name} toast has been added`;
  },
  error: "Error",
});

参考资料

添加 Mermaid 支持

支持图表是必须的，用不用再说。

安装依赖

npm install @docusaurus/theme-mermaid

配置

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

区别 `.md` 和 `.mdx`

默认情况下，Docusaurus 对 .md 文件，.mdx 用一样的规则解析，也就是都当成 MDX。这不太好，因为 MDX 支持 JSX 相当于格式更加严格了。虽然说兼容 Markdown，但是是有例外的。为了不必要的麻烦。我觉得还是区分 .md 和 .mdx 比较合适。如果内容没有任何动态信息，直接用 .md 就可以了。不用担心解析错误。如果有动态内容，手动改为 .mdx 再加动态内容。

配置

{
  markdown: {
    format: "detect",
  },
}

加速构建

据说提速明显

安装依赖

npm install --save-dev @docusaurus/faster

配置

{
  future: {
    experimental_faster: true,
  },
}

配置语法高亮

{
  themeConfig: ({
    prism: {
      theme: prismThemes.vsDark, // 默认主题
      darkTheme: prismThemes.dracula, // 暗黑主题
      additionalLanguages: ["diff"], // 添加 diff 语言支持
    },
  });
}

注：可选的主题有：https://github.com/FormidableLabs/prism-react-renderer/tree/master/packages/prism-react-renderer/src/themes

配置 Sitemap

由于使用的是 Docusaurus 的 classic 模板，所以直接配置即可，不需要安装依赖了。

{
  sitemap: {
    changefreq: "weekly",
    priority: 0.5,
    ignorePatterns: ["/tags/**"],
    filename: "sitemap.xml",
  },
}

开发环境访问不到，build 以后就能看到了。

配置 RSS

由于使用的是 Docusaurus 的 classic 模板，所以内置了 Blog 的 RSS，路径是 /blog/rss.xml。开发环境访问不到，build 以后就能看到了。

配置 GA 统计

安装依赖

pnpm add @docusaurus/plugin-google-gtag

配置

{
  plugins: [
    [
      "@docusaurus/plugin-google-gtag",
      {
        trackingID: "GA_TRACKING_ID",
        anonymizeIP: true,
      },
    ],
  ],
}

配置本地搜索

这里使用的插件是： docusaurus-lunr-search

安装依赖

pnpm add docusaurus-lunr-search
pnpm add lunr

配置

docusaurus.config.js
{
  module.exports = {
    // ...
    plugins: [require.resolve("docusaurus-lunr-search")],
  };
}

插件还支持一些个性化配置项，不过我用默认的效果貌似也挺好的。

如何给每个博客添加一个头图

一般博客正文页都有个头图，你可以精心挑选，并提供资源图片链接。我这里的思路是图文无关，随机显示，图片也来自于网上免费的图片资源。有两个选择，一个是 picsum.photos，另一个是 upsplash，后者已经禁用了直接随机图片链接方式，只能用 API 来获取，略显麻烦，暂时先不采用，后续前一个失效了再来关注。

依赖提升

如果使用 npm, yarn 不需要这一步，但是如果用 pnpm，一个重点特性就是解决幻影依赖，但是这里要用到幻影依赖。

.npmrc

public-hoist-pattern[]=*@docusaurus/*

然后重新安装依赖

pnpm install

这时你去看 node_modules 目录，会发现 @docusaurus 目录下多了很多文件夹，这就是幻影依赖。

Swizzle

为了自动让每个博客正文都显示一个头图，我们需要 swizzle 一下。

pnpm run swizzle @docusaurus/theme-classic BlogPostItem --eject

然后就会发现 src/theme/BlogPostItem/index.js 文件被创建了。其他还有许多关联文件，保持原样。

头图逻辑

import React from "react";
import clsx from "clsx";
import { useBlogPost } from "@docusaurus/plugin-content-blog/client";
import BlogPostItemContainer from "@theme/BlogPostItem/Container";
import BlogPostItemHeader from "@theme/BlogPostItem/Header";
import BlogPostItemContent from "@theme/BlogPostItem/Content";
import BlogPostItemFooter from "@theme/BlogPostItem/Footer";
// apply a bottom margin in list view
function useContainerClassName() {
  const { isBlogPostPage } = useBlogPost();
  return !isBlogPostPage ? "margin-bottom--xl" : undefined;
}
export default function BlogPostItem({ children, className }) {
  const containerClassName = useContainerClassName();
  const { isBlogPostPage } = useBlogPost();
  // 生成随机图片 URL，添加时间戳防止缓存
  const randomImageUrl = `https://picsum.photos/800/400?random=${Date.now()}`;
  return (
    <BlogPostItemContainer className={clsx(containerClassName, className)}>
      <BlogPostItemHeader />
      {/* 在标题和正文之间插入随机图片 */}
      {isBlogPostPage && (
        <>
          <img
            src={randomImageUrl}
            alt="Random Image"
            className="w-full h-auto rounded-lg shadow-md max-w-full block mx-auto"
          />
          <div className="mx-auto flex justify-center -mt-4 mb-4 text-sm text-gray-400">
            图片与正文无关
          </div>
        </>
      )}
      <BlogPostItemContent>{children}</BlogPostItemContent>
      <BlogPostItemFooter />
    </BlogPostItemContainer>
  );
}

整合 Tailwind CSS​

安装依赖​

添加插件​

添加配置​

配置 custom.css​

暗色兼容 TailwindCSS​

参考资料​

整合 TailwindCSS Typography 插件​

安装依赖​

配置 custom.css​

覆盖 <BlogPostItem> 组件​

整合 shadcn/ui​

安装依赖​

添加 jsconfig.json​

配置全局样式​

添加助手函数 lib/utils.js​

创建 components.json 文件​

添加适配插件 alias-config.js​

添加 toast 组件​

安装依赖​

覆盖默认 Layout​

然后编辑这个 Wrap Layout​

参考资料​

添加 Mermaid 支持​

安装依赖​

配置​

区别 .md 和 .mdx​

配置​

加速构建​

安装依赖​

配置​

配置语法高亮​

配置 Sitemap​

配置 RSS​

配置 GA 统计​

安装依赖​

配置​

配置本地搜索​

安装依赖​

配置​

如何给每个博客添加一个头图​

依赖提升​

Swizzle​

头图逻辑​

整合 Tailwind CSS

安装依赖

添加插件

添加配置

配置 `custom.css`

暗色兼容 `TailwindCSS`

参考资料

整合 TailwindCSS Typography 插件

安装依赖

配置 `custom.css`

覆盖 `<BlogPostItem>` 组件

整合 `shadcn/ui`

安装依赖

添加 `jsconfig.json`

配置全局样式

添加助手函数 `lib/utils.js`

创建 `components.json` 文件

添加适配插件 `alias-config.js`

添加 toast 组件

安装依赖

覆盖默认 Layout

然后编辑这个 Wrap Layout

参考资料

添加 Mermaid 支持

安装依赖

配置

区别 `.md` 和 `.mdx`

配置

加速构建

安装依赖

配置

配置语法高亮

配置 Sitemap

配置 RSS

配置 GA 统计

安装依赖

配置

配置本地搜索

安装依赖

配置

如何给每个博客添加一个头图

依赖提升

Swizzle

头图逻辑