如何搭建博客

这篇文章是当时基于 Docusaurus 的实践记录，涵盖了主要决策过程和排障路径，供后续迁移时参考。

Docusaurus

创建项目

pnpm create docusaurus

根据提示选择即可。

配置博客模式

module.exports = {
  presets: [
    [
      "@docusaurus/preset-classic",
      {
        docs: false,
        blog: {
          routeBasePath: "/",
        },
      },
    ],
  ],
};

google analytics

Google Analytics 4 可通过 plugin-google-gtag 接入。

安装依赖

pnpm install @docusaurus/plugin-google-analytics

配置

module.exports = {
  presets: [
    [
      "@docusaurus/preset-classic",
      {
        googleAnalytics: {
          trackingID: "",
          anonymizeIP: true,
        },
      },
    ],
  ],
};

百度统计

Docusaurus 提供了灵活的插件机制，方便我们实现想要的功能。

自定义插件

在 src/plugins/plugin-baidu-analytics 目录下创建 index.js。

module.exports = function (context, options) {
  const isProd = process.env.NODE_ENV === "production";
  // 获取配置中的trackingID参数
  const { trackingID } = options;
  return {
    name: "plugin-baidu-analytics",
    injectHtmlTags({ content }) {
      if (!isProd) {
        return {};
      }
      return {
        headTags: [
          {
            tagName: "link",
            attributes: {
              rel: "preconnect",
              href: "https://hm.baidu.com",
            },
          },
          {
            tagName: "script",
            attributes: {
              async: true,
              src: `https://hm.baidu.com/hm.js?${trackingID}`,
            },
          },
        ],
      };
    },
  };
};

使用插件

在 百度站点管理 获取 trackingID。

plugins: [
  "@docusaurus/theme-live-codeblock",
+  [
+    require("./src/plugins/plugin-baidu-analytics"),
+    { trackingID: "" }, //  传入trackingID参数
+  ],
],

可交互的代码编辑器并实时预览

安装依赖

pnpm install @docusaurus/theme-live-codeblock

配置

module.exports = {
  plugins: ["@docusaurus/theme-live-codeblock"],
  themeConfig: {
    liveCodeBlock: {
      /**
       * 实时效果显示的位置，可位于编辑器上方或下方。
       * 可为："top" | "bottom"
       */
      playgroundPosition: "bottom",
    },
  },
};

使用

创建代码块，添加代码块语言标签，再在语言标签后面添加 live。

```jsx live
function Clock(props) {
  const [date, setDate] = useState(new Date());
  useEffect(() => {
    var timerID = setInterval(() => tick(), 1000);

    return function cleanup() {
      clearInterval(timerID);
    };
  });

  function tick() {
    setDate(new Date());
  }

  return (
    <div>
      <h2>It is {date.toLocaleTimeString()}.</h2>
    </div>
  );
}

代码块将渲染为可交互的代码编辑器，并实时预览。

function Clock(props) {
  const [date, setDate] = useState(new Date());
  useEffect(() => {
    var timerID = setInterval(() => tick(), 1000);

    return function cleanup() {
      clearInterval(timerID);
    };
  });

  function tick() {
    setDate(new Date());
  }

  return (
    <div>
      <h2>It is {date.toLocaleTimeString()}.</h2>
    </div>
  );
}

国际化

配置

+ i18n: {
+    defaultLocale: "zh",
+    locales: ["zh"],
+    localeConfigs: {
+        zh: {
+            htmlLang: "zh-CN"
+        }
+    }
+ }

翻译

有些英文文案没有翻译，因此需要重写翻译文件。

pnpm run write-translations -- --locale zh

支持 mermaid 作图

安装依赖

pnpm i mermaid mdx-mermaid -D

配置

blog: {
    routeBasePath: "/",
+   remarkPlugins: [require("mdx-mermaid")]
},

使用

查看 mermaid 官网 文档。

graph
A --> B

阅读时间

blog: {
    routeBasePath: "/",
+   showReadingTime: true,
},

sitemap

方便搜索引擎爬虫更准确地抓取网站。

安装依赖

pnpm i @docusaurus/plugin-sitemap

配置

module.exports = {
  presets: [
    [
      'classic',
      (
+      {
+        sitemap: {
+          changefreq: 'weekly',
+          priority: 0.5,
+        },
+      },
      )
    ],
  ],
};

搜索

使用本地搜索，目前已经够用。

安装依赖

pnpm i @easyops-cn/docusaurus-search-local

配置

+ themes: [
+   [
+     require.resolve("@easyops-cn/docusaurus-search-local"),
+     { hashed: true, language: ["en", "zh"], blogRouteBasePath: "/", },
+   ],
+ ],

归档、标签链接

navbar: {
  ...
  items: [
    {
      to: "/tags",
      label: "标签",
      position: "right",
    },
    {
      to: "/archive",
      label: "归档",
      position: "right",
    },

swc 替换 babel

使用 swc-loader 加速编译和打包。

安装依赖

pnpm i swc-loader @swc/core -D

配置

webpack: {
  jsLoader: (isServer) => ({
    loader: require.resolve("swc-loader"),
    options: {
      jsc: {
        parser: {
          syntax: "typescript",
          tsx: true,
        },
        target: "es2017",
      },
      module: {
        type: isServer ? "commonjs" : "es6",
      },
    },
  }),
},

GitHub

源代码直接托管在 GitHub 上。

Vercel

博客直接部署在 Vercel 上。部署简单，一键完成，还支持 CDN。

域名

购买域名，并在 Vercel 中配置为使用自己的域名。