Docusaurus 框架

介绍

Docusaurus：文档龙/多库龙。

参考资料

官网：Build optimized websites quickly, focus on your content | Docusaurus
Docusaurus 与其他框架的对比：Comparison with other tools - Docusaurus
示例站点

使用

快速搭建

快速搭建

bash

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 目录

text

├── 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 中添加、修改如下设置：

  // 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,

示例：

yml

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 自动生成
// 单个导航栏
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 文件

json

{
  "label": "XXX",
  "position": 2,
  "link": {
    "type": "generated-index",
    "description": "XXX"
  }
}

手动生成 sidebar 时，可在 sidebar.js 文件中添加 link 参数，自动生成子目录文件索引

首页内容修改

去掉首页中间的下半部分，自定义上半部分
- 参考：GitHub - anitabi/navi.anitabi.cn: 动画巡礼帮助文档
- 下半部分：src/components/HomepageFeatures/index.js，注释 FeatureList 相关内容
- 上半部分：src/pages/index.js，修改 button 属性的文字内容
首页内容使用 md 文档（本地预览不会报错、build 会报错）
- Docs Introduction | Docusaurus
- docusaurus - How to set "Docs" as the main page - Stack Overflow
- 先在 docusaurus.config.js 中的 docs 选项中添加 routeBasePath: '/' 参数，之后在 docs 目录下的任意 md 文件中添加 slug: / front matter，之后再删掉 src/pages/index.js 文件

搜索

搜索功能：search - Docusaurus

Docusaurus 框架 ​

介绍 ​

参考资料 ​

使用 ​

快速搭建 ​

部署 ​

配置 ​

常用参数设置 ​

侧边栏生成 ​

子目录文件索引 ​

首页内容修改 ​

搜索 ​

Docusaurus 框架

介绍

参考资料

使用

快速搭建

部署

配置

常用参数设置

侧边栏生成

子目录文件索引

首页内容修改

搜索