Docusaurus 框架

介绍

Docusaurus：文档龙/多库龙。

参考资料

使用

快速搭建

  • 快速搭建
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
npx create-docusaurus@latest docusaurus-demo classic

cd docusaurus-demo

# 安装依赖
yarn        # npm i 
# 本地预览
yarn start  # npm run start
# 构建
yarn build  # npm run build 

# 部署 若使用 GitHub 托管，会推送到 gh-pages 分支
# 使用 SSH
USE_SSH=true yarn deploy
# 不使用 SSH
GIT_USER=<Your GitHub username> yarn deploy

# 查看版本
npx docusaurus --version

# 若已绑定域名，可将 CNAME 放入 static 目录
  • 目录结构
1
2
3
4
5
6
7
8
9
├── README.md
├── babel.config.js
├── blog/  # 可删除
├── docs/
├── docusaurus.config.js
├── package.json
├── sidebars.js
├── src/
└── static/

部署

Deploying to GitHub Pages - Docusaurus

  • 手动：USE_SSH=true npm run deploy

  • GitHub Actions：

    • 用哪个包管理工具（npm、yarn、pnpm）安装依赖、构建，需在 Github Actions 修改为对应的命令
    • 部署及站点 URL 设置：在 docusaurus.config.js 中添加、修改如下设置：
1
2
3
4
5
6
7
8
9
// Set the production url of your site here
url: 'https://username.github.io/',
baseUrl: '/docusaurus-demo/',

// GitHub pages deployment config.
organizationName: 'username',
projectName: 'docusaurus-demo',
deploymentBranch: 'gh-pages',
trailingSlash: false,

示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
name: Docusaurus Deploy

on:
  push:
    branche:
      - main

permissions:
  contents: write

jobs:
  deploy:
    name: Deploy to GitHub Pages
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: latest

      - name: Install dependencies
        run: npm install
      - name: Build website
        run: npm run build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

配置

配置文件参考：

常用参数设置

配置文件 docusaurus.config.js 常用参数：

  • presets - 预定义配置，如 docs、blog 和 theme 参数灯

    • docs - 配置文档，如文件夹路径 path、侧边栏 sidebarPath 等
    • blog - 配置博客，如文件夹的路径等

  • themeConfig - 主题配置，如 navbar、footer、浅/深色模式等

    • navbar - 配置顶部导航栏，如导航栏条目对应的侧边栏
    • footer - 配置页脚，如链接、copyright

侧边栏生成

  • 自动生成侧边栏默认是按 md 文档标题的字母顺序排列的
    • 可在 md 文档中添加 sidebar_position front matter 自定义调整标题的前后位置
    • 可在 _category_.json 文件中添加 position 参数自定义调整子目录文档在整个标题的前后位置
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// 方式 1 自动生成
// 单个导航栏
tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
// 多个导航栏
softwareSidebar: [{type: 'autogenerated', dirName: 'softwares'}],
scitoolSidebar: [{type: 'autogenerated', dirName: 'scitoolkits'}],

// 手动生成
scitoolSidebar: [
  'scitoolkits/index',
  'scitoolkits/glossary',
  {
    label: 'atomate',
    type: 'category',
    link: { // 自动生成子目录文件索引
      type: 'generated-index',
    },
    items: [
      'scitoolkits/atomate/atomate-usage',
    ],
  },
],

子目录文件索引

  • docs/ 目录下的子目录生成文件索引，需添加 _category_.json 文件
1
2
3
4
5
6
7
8
{
  "label": "XXX",
  "position": 2,
  "link": {
    "type": "generated-index",
    "description": "XXX"
  }
}
  • 手动生成 sidebar 时，可在 sidebar.js 文件中添加 link 参数，自动生成子目录文件索引

首页内容修改

搜索

  • 搜索功能：search - Docusaurus

  • 使用 Algolia DocSearch：Docusaurus 自带的 @docusaurus/preset-classic 支持 Algolia DocSearch 集成，无需安装依赖；添加以下 Algolia 设置

1
2
3
4
5
6
7
8
9
10
11
themeConfig: {
  // ...
  algolia: {
    // The application ID provided by Algolia
    appId: 'XXX',
    // Public API key: it is safe to commit it
    apiKey: 'XXX',
    indexName: 'docusaurus-demo',
    // 其余参数均为可选
  },
}