使用指南

docusaurus 项目结构简介

        my-docusaurus-project/
        ├── docs/                     # 文档内容
        │   ├── intro.md              # intro.md 文件名会被转换为 /intro 路径
        │   ├── folder/               # 子目录
        │   │   ├── doc1.md           # /folder/doc1 路径
        │   │   └── doc2.md           # /folder/doc2 路径
        │   └── ...
        ├── src/                      # 自定义的源代码
        │   ├── css/                  # 用于主题的自定义 CSS
        │   ├── components/           # 自定义 React 组件
        │   └── ...
        ├── static/                   # 静态资源（图片、样式等）
        │   ├── img/
        │   └── ...
        ├── docusaurus.config.js      # Docusaurus 的配置文件
        ├── package.json              # 项目依赖和脚本
        └── sidebar.js                # 定义文档页面的侧边栏

docs/: 存放 Markdown 格式的文档。每个文件或子目录将成为网站的一个单独部分。
src/: 针对 Docusaurus 默认设置的自定义源代码目录。常用于添加自定义 CSS 和 React 组件。
static/: 用于存储静态资源，如图片、样式表等。这些资源会直接复制到构建后的网站根目录，便于引用。
docusaurus.config.js: Docusaurus 的核心配置文件，包括站点元数据、导航、插件、主题等设置。
package.json: 标准的 npm 配置文件，定义了项目的依赖和运行脚本。例如，通过 npm run start 使用此文件中的脚本启动项目。
sidebar.js: 定义文档页面的侧边栏布局。你可以设定侧边栏的文档显示顺序和结构。

docusaurus 脚本命令

Docusaurus 提供了一系列命令来协助开发和部署文档网站：

docusaurus: Docusaurus 的核心入口，但通常我们不直接使用它。
dev (docusaurus start): 运行开发服务器，支持热重载。这使得编辑时可以实时查看更改。
build (docusaurus build): 将你的文档网站生成为静态文件，适合部署到各种静态文件托管服务。
swizzle (docusaurus swizzle): 通过“Swizzling”特性，你可以覆盖默认的主题组件进行个性化定制。
deploy (docusaurus deploy): 专为 GitHub Pages 设计的部署辅助工具，使得部署过程更加便捷。
clear (docusaurus clear): 清除项目的缓存和临时文件，有助于解决某些构建问题。
serve (docusaurus serve): 在本地预览构建的 Docusaurus 网站，方便部署前的检查。
write-translations (docusaurus write-translations): 管理文档翻译的工具，将默认翻译从源代码提取，方便后续的翻译工作。
write-heading-ids (docusaurus write-heading-ids): 为文档中的标题生成唯一 ID，允许创建指向特定章节的链接。

使用`deploy`命令

使用此命令需要配合GIT_USER

#!/bin/bash
GIT_USER=sumingcheng docusaurus deploy

配置导航

sidebars.js

/**
 * 创建一个侧边栏允许你：
 * 创建一个有序的文档组
 * 为该组的每一个文档渲染一个侧边栏
 * 提供下一步/上一步的导航
 * 侧边栏可以从文件系统生成，或者在这里显式地定义。
 * 根据需要创建尽可能多的侧边栏。
 */

const sidebars = {
  // 默认情况下，Docusaurus 从 docs 文件夹结构中生成一个侧边栏
  // tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
  learnSidebar: [{ type: 'autogenerated', dirName: 'learning' }],
  thoughtsSidebar: [{ type: 'autogenerated', dirName: 'thoughts' }],
  translationsSidebar: [{ type: 'autogenerated', dirName: 'translations' }],
  resourceSidebar: [{ type: 'autogenerated', dirName: 'resource' }],
};

module.exports = sidebars; // 导出侧边栏的配置

docusaurus.config.js

    navbar: {
      title: 'SMC docs', // 导航栏标题
      logo: {
        alt: '素明诚', // logo的替代文本
        src: 'img/mini.ico' // logo的路径
      },
      items: [
        // {to: '/blog', label: 'Blog', position: 'right'},
        {
          type: 'docSidebar',
          sidebarId: 'learnSidebar',
          position: 'right',
          label: '学习资料'
        },
        {
          type: 'docSidebar',
          sidebarId: 'thoughtsSidebar',
          position: 'right',
          label: '思考碎片'
        },
        {
          type: 'docSidebar',
          sidebarId: 'translationsSidebar',
          position: 'right',
          label: '译文集'
        },
        {
          type: 'docSidebar',
          sidebarId: 'resourceSidebar',
          position: 'right',
          label: '资源'
        },
        {
          href: 'https://github.com/sumingcheng',
          'aria-label': 'GitHub repository',
          position: 'right',
          className: 'github-icon'
        }
      ]
    }

docusaurus 项目结构简介​

docusaurus 脚本命令​

使用deploy命令​

配置导航​

docusaurus 项目结构简介

docusaurus 脚本命令

使用`deploy`命令

配置导航