跳到主要内容

使用Docusaurus搭建博客

背景​

之前博客一直用的本地版Gitbook，但确实太老了，官方也不维护，编译效率低，再加上看久了审美疲劳，决定重搞一下。

找了一下竞品，发现Facebook的Docusaurus还不错，文档也很详细：

⚡️ Docusaurus能帮你迅速打造出一个美观的文档网站。

搭建​

官方文档很清楚了，快速启动如下：

# 使用 create-docusaurus 自动配置，运行后会让你选配置，按需选择即可
npx create-docusaurus@latest my-website classic

生成目录结构如下：

my-website
├── blog // 包含博客Markdown文件的目录
│   ├── 2019-05-28-hola.md // 具体的博客Markdown文件
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs // 包含文档Markdown文件的目录
│   ├── doc1.md // 具体的文档Markdown文件
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── src // 存放非文档文件（如页面或自定义React组件）的目录
│   ├── css
│   │   └── custom.css
│   └── pages // 存放页面相关文件的目录
│       ├── styles.module.css // 页面样式文件
│       └── index.js // 首页
├── static // 静态资源目录，内容会被复制到最终build目录的根目录
│   └── img
├── docusaurus.config.js // 站点配置文件，相当于Docusaurus v1中的siteConfig.js
├── package.json // Docusaurus网站作为React应用的包管理文件，可安装和使用npm包
├── README.md // 项目的说明文档
├── sidebars.js // 用于指定文档侧边栏中文档顺序的文件
└── yarn.lock // Yarn包管理器的锁定文件，记录依赖包的具体版本

二选一启动项目（开发模式，动态更新）：

cd my-website
# 如下命令2选1即可
npm run start
yarn run start

编译成可以发布的静态文件（可以托管到 GitHub 页面、Vercel 或 Netlify）：

npm run build
yarn build

配置​

核心配置文件 docusaurus.config.js，如果看英语困难可以让AI帮你把注释全部改成中文：

  • 修改基础数据，如标题、图标、跳转链接等等
  • 配置主题、安装插件
  • ...

因为我主要用其docs插件，所以还重点关注plugin-content-docs的配置

后面几乎就是按自己想法来改就行，改不来也不要紧，直接问AI，包括首页直接给他张图即可。

建议1​

某些文件夹的内容不显示，在docusaurus.config.js中修改。

  # 在 presets 的 docs 目录下
  // 过滤掉 tutorial-basics 目录
  exclude: ['tutorial-basics/**'],

建议2​

配置每页右侧目录显示层级（默认是3）

  1. 把 node_modules/@docusaurus/theme-classic/src/theme/DocItem复制到/src/theme/DocItem
  2. 修改 maxHeadingLevel={5} 即可全局生效，右侧目录可以显示多级

建议3​

默认情况下编译时不允许有不可访问的URL，在docusaurus.config.js中修改。

onBrokenLinks: 'warn',

建议4​

给每个目录自动生成 _category_.json 文件，编写sh脚本如下：

#!/bin/bash

# 退出时遇到错误
set -e

# 检查是否传入参数
if [ -z "$1" ]; then
  echo "❌ 请传入要处理的根目录，例如："
  echo "   $0 ."
  echo "   $0 ../src"
  echo "   $0 /绝对路径"
  exit 1
fi

# 获取用户传入的目录路径
ROOT_DIR="$1"

# 检查目录是否存在
if [ ! -d "$ROOT_DIR" ]; then
  echo "❌ 指定的目录不存在: $ROOT_DIR"
  exit 1
fi

echo "📁 正在处理目录: $ROOT_DIR"

# 遍历所有子目录
find "$ROOT_DIR" -type d | while read -r dir; do

  # 是否包含 .md 或 .mdx 文件
  if find "$dir" -maxdepth 1 -type f \( -iname "*.md" -o -iname "*.mdx" \) | grep -q .; then

    FILE_PATH="$dir/_category_.json"

    # 如果 _category_.json 已存在则跳过
    if [ -f "$FILE_PATH" ]; then
      echo "⏩ 已存在，跳过: $FILE_PATH"
      continue
    fi

    # 写入内容
    cat <<EOF > "$FILE_PATH"
{
  "link": {
    "type": "generated-index",
    "description": " "
  }
}
EOF

    echo "✅ 已生成: $FILE_PATH"
  fi

done

echo "🎉 所有目录处理完成！"

建议5​

在支持高亮语言列表中有所有支持的语言，但默认开启的只有部分，为其他语言开启高亮，在docusaurus.config.js中修改。

// themeConfig 下的 prism 中添加 additionalLanguages 字段
      prism: {
        theme: prismThemes.github,
        darkTheme: prismThemes.oneDark,
        additionalLanguages: ['powershell', 'bash'], // 这一行
      }

建议6​

增加搜索框，参考文档search：Using Algolia DocSearch，先去网站上申请，申请通过后会给你发邮件，然后登陆 Crawler Admin Console 就可以看到自己的网站了。

然后将得到 algolia 的 appId，apiKey，indexName 填写到 docusaurus.config.ts 中的themeConfig下即可。

export default {
  // ...
  themeConfig: {
    algolia: {
      // The application ID provided by Algolia
      appId: '0LMFVYF6KV',
      // Public API key: it is safe to commit it
      apiKey: 'cb7b339726113f00161e5e4c8b4bf94d',
      indexName: 'gm7',
    },
  },
};
注意

一定要仔细看官方文档，替换相关的爬虫配置信息。

建议7​

一些推荐的插件：

plugin-image-zoom​

适用于 Docusaurus 的图像缩放插件。

npm install flexanalytics/plugin-image-zoom

在docusaurus.config.js中配置如下：

  plugins: [
    'plugin-image-zoom',
  ],

plugin-baidu-analytics​

百度统计

npm install @gracefullight/docusaurus-plugin-baidu-analytics

在docusaurus.config.js中配置如下：

plugins: [
    [
      "@gracefullight/docusaurus-plugin-baidu-analytics",
      { siteId: "3675030a9721336abea8cd0e46b3f76b" }, // 换成你的token
    ],
  ],

其他​

找到一个大佬开源的模板：https://github.com/kuizuo/blog，基本上想要的功能都有，而且排版啥的也挺好的，建议直接Star⭐️！在这个基础上去定制化会更容易。

最后由 d4m1ts 于 更新