用 Docusaurus 创建属于自己的博客

2024年12月22日 · 阅读需 10 分钟

之前我一直使用 Jekyll 构建我的博客，直到偶然接触到 Docusaurus 并立即被其吸引，于是决定尝试迁移。

Docusaurus 提供了简洁直观的用户界面、强大的代码块展示功能、活跃的社区支持以及丰富的插件生态，加上由 Meta（原 Facebook）维护的背景，这些优点让我对它一见钟情。

在转移过程中，我梳理了从基础安装到契合我个人需求的相关操作内容。

什么是 Docusaurus

Docusaurus 是一个基于 React 和 MDX 的静态网站生成工具，现在由 Meta 维护，是一个开源项目。它的设计初衷是让用户能够快速、轻松地创建文档类网站。

以下是它的一些主要特点：

文档与博客功能：强大的文档支持，同时能轻松创建多种类型的网站。
基于 MDX：结合 Markdown 语法与 React 组件，支持扩展性的内容创作。
多语言支持 (i18n)：轻松实现多语言网站。
SEO 友好：自动生成站点地图（sitemap）和元标签（meta tags）等。
代码块：支持强大的 Syntax highlighting 功能。
易于部署：支持在 Vercel、GitHub Pagesl、Netlify 等平台上轻松部署。

安装

在安装 Node.js 后，可以通过以下命令创建一个新的 Docusaurus 项目：

npx create-docusaurus@latest my-site classic --typescript

# 启动本地开发服务器
cd my-site
npm run start

正常情况下，访问 http://localhost:3000 后应该能看到默认的 Docusaurus 页面。

Blog-only 模式

如果你不打算要额外的着陆页，并希望首页直接展示博文列表，可以进行如下修改：

删除 ./src/pages/index.{js,tsx} 文件，以防止多个文件映射到同一路径。
在 docusaurus.config.ts 中，将blog模块的 routeBasePath 设置为根路径 /：

docusaurus.config.ts
export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: false, // Optional: disable the docs plugin
        blog: {
          routeBasePath: '/', // Serve the blog at the site's root
          // ...
        },
      },
    ],
  ],
};

多语言 (i18n) 配置

随着 ChatGPT 等工具的出现，管理和运营多语言博客变得更为简便。Docusaurus 内置了 i18n 支持，通过简单的设置即可添加多种语言。

1. 多语言配置

docusaurus.config.ts
export default {
  i18n: {
    defaultLocale: 'zh-Hans',
    locales: ['zh-Hans', 'en'],
    localeConfigs: {
      'zh-Hans': {
        label: '中文',
        htmlLang: 'zh-CN',
      },
    }
  },
  themeConfig: {
    navbar: {
      items: [
        // ...
        {
          type: 'localeDropdown', position: 'left',
        },
        // ...
      ],
    },
  },
  // ...
};

2. 生成多语言文件

利用 write-translations 命令，根据配置的语言自动生成 i18n 目录及其 JSON 文件，用于存储各语言的内容，以便后续翻译工作。

npm run write-translations -- --locale zh-Hans
npm run write-translations -- --locale en

> my-site@0.0.0 write-translations
> docusaurus write-translations --locale en

[INFO] 78 translations will be written at "i18n/en/code.json".
[INFO] 5 translations will be written at "i18n/en/docusaurus-theme-classic/navbar.json".
[INFO] 10 translations will be written at "i18n/en/docusaurus-theme-classic/footer.json".
[INFO] 4 translations will be written at "i18n/en/docusaurus-plugin-content-docs/current.json".
[INFO] 3 translations will be written at "i18n/en/docusaurus-plugin-content-blog/options.json".

将默认语言的文章存放在 /blog 下，然后将其复制到 my-site/i18n/[locale]/docusaurus-plugin-content-blog 目录中，完成相应翻译。

my-site/i18n/[locale]/docusaurus-plugin-content-blog
│
│ # 已翻译的博文
├── authors.yml
├── first-blog-post.md
├── second-blog-post.md
│
│ # plugin options的翻译
└── options.json

SEO - sitemap配置

production only

此功能仅在生产环境中启用。

Docusaurus 默认集成了 plugin-sitemap，只需简单配置即可启用：

docusaurus.config.ts
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        sitemap: {
          lastmod: 'date',
          changefreq: 'weekly',
          priority: 0.5,
          ignorePatterns: ['/tags/**'],
          filename: 'sitemap.xml',
          createSitemapItems: async (params) => {
            const {defaultCreateSitemapItems, ...rest} = params;
            const items = await defaultCreateSitemapItems(rest);
            return items.filter((item) => !item.url.includes('/page/'));
          },
        },
      },
    ],
  ],
};

需要注意的是，当配置 i18n 后，每种语言都会生成独立的sitemap。

Code blocks

Docusaurus 的代码块功能非常强大，尽管 Docusaurus 默认支持多种编程语言的语法高亮，但某些常用语言（如 Java、Bash）可能需要手动添加支持(默认启用的语言)：

docusaurus.config.ts
export default {
  // ...
  themeConfig: {
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
      additionalLanguages: ['bash','java','properties']
    },
    // ...
  },
};

此外，还可以通过 highlight-next-line, highlight-start, highlight-end 等注解实现line-highlighting 功能。

Google 整合

Google Analytics 配置

production only

此功能仅在生产环境中启用。

只需通过预设配置项，Docusaurus 即可轻松集成 Google Analytics：

docusaurus.config.ts
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        gtag: {
          trackingID: 'G-999X9XX9XX',
          anonymizeIP: true,
        },
      },
    ],
  ],
};

Google Adsense 的集成非常简单，只需要加载对应的脚本即可。可以使用 Docusaurus Scripts功能来实现这一点。

docusaurus.config.ts
export default {
  scripts: [
    {
      src: 'https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-XXXXXXX',
      async: true,
      crossorigin: 'anonymous',
    },
  ],
};

URL迁移

在迁移博客时，如果 URL 结构发生变化，可能会导致链接失效。为了避免这种情况，需要进行 URL 迁移工作。Docusaurus 支持通过 slug 设置或重定向方式进行 URL 迁移。

Front Matter - `slug`

Docusaurus 的 front matter 中可以使用 slug 属性自由设置博客文章或页面的 URL。例如，可以通过 slug 值将 /2024/12/24/welcome 格式的 URL 更改为 /welcome。

---
title: "welcome"
slug: "/welcome"
tags: ["docusaurus"]
---

my doc

Redirects

在URL迁移时，重定向也是一种常用方法。Docusaurus支持客户端重定向，但这对SEO来说并不是最佳方式。

有经验的用户可能了解，最符合SEO的重定向方式是 Server-side redirects。

The following table explains the various ways you can use to set up permanent and temporary redirects, ordered by how likely Google is able to interpret correctly (for example, a server side redirect has the highest chance of being interpreted correctly by Google). Choose the redirect type that works for your situation and site:

Server-side redirect (推荐)

Google官方文档能看到，使用服务端(301)重定向不会影响Page rank。

相关Google文档：General best practices for site moves

301, 302, and other server side redirects don't cause a loss in PageRank.

相比之下，客户端重定向有时可能无法被搜索引擎正确处理，或者新的URL无法获得适当的评估。

根据您的托管方式，可以参考以下文档：

Vercel: Vercel: redirects
Netlify: Netlify: redirects
Self hosting: Google文档
GitHub Pages：不支持服务端重定向功能。

Client-side redirect

对于无法实现服务端重定向或不需要关注SEO的情况，可以使用@docusaurus/plugin-client-redirects插件实现简单的客户端重定向。

@docusaurus/plugin-client-redirects安装:

npm install --save @docusaurus/plugin-client-redirects

配置示例：

docusaurus.config.ts
export default {
  plugins: [
    [
      '@docusaurus/plugin-client-redirects',
      {
        fromExtensions: ['html', 'htm'], // /myPage.html -> /myPage
        toExtensions: ['exe', 'zip'], // /myAsset -> /myAsset.zip (if latter exists)
        redirects: [
          // /docs/oldDoc -> /docs/newDoc
          { to: '/docs/newDoc', from: '/docs/oldDoc',},
          // Redirect from multiple old paths to the new path
          { to: '/docs/newDoc2', from: ['/docs/oldDocFrom2019', '/docs/legacyDocFrom2016'],},
        ],
        createRedirects(existingPath) {
          if (existingPath.includes('/community')) {
            // Redirect from /docs/team/X to /community/X and /docs/support/X to /community/X
            return [
              existingPath.replace('/community', '/docs/team'),
              existingPath.replace('/community', '/docs/support'),
            ];
          }
          return undefined; // Return a falsy value: no redirect created
        },
      },
    ],
  ],
};

部署 (CI/CD)

选择托管平台时，Vercel、GitHub Pages、Netlify 等都是不错的选择。

作为一位长期使用 Vercel 的用户，我特别推荐新手选择 Vercel，因为它的设置过程极其简便，只需几次点击就能将 GitHub 项目导入并配置 CI/CD 流程。

官方文档: How to Deploy a Docusaurus Site with Vercel

结语

花了一个周末的时间，完成了从Jekyll到Docusaurus的迁移。

在这篇文章里，我总结了从基本设置到迁移的关键步骤和实用技巧，希望能帮助有需要的朋友轻松构建出自己理想的网站。

什么是 Docusaurus​

安装​

Blog-only 模式​

多语言 (i18n) 配置​

1. 多语言配置​

2. 生成多语言文件​

SEO - sitemap配置​

Code blocks​

Google 整合​

Google Analytics 配置​

Google Adsense 集成​

URL迁移​

Front Matter - slug​

Redirects​

Server-side redirect (推荐)​

Client-side redirect​

部署 (CI/CD)​

结语​