主配置文件

Docusaurus 的主配置文件是 docusaurus.config.js（或 .ts），它是一个标准的 JavaScript（或 TypeScript）导出对象，整个项目的运行和行为基本都由它控制。

docusaurus.config.js 配置

docusaurus.config.js

import { themes as prismThemes } from 'prism-react-renderer';

/** @type {import('@docusaurus/types').Config} */
const config = {
  // 网站基础信息
  title: '知识速看',
  tagline: '专注简洁、高效的技术文档',
  url: 'https://www.zxzsk.com', // 站点部署域名
  baseUrl: '/',                 // 根路径，通常为 '/'，如果部署在子路径请调整
  favicon: 'img/favicon.ico',

  // 国际化配置（仅使用中文）
  i18n: {
    defaultLocale: 'zh-CN',
    locales: ['zh-CN'],
  },

  // 链接错误处理
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',

  // 启用文档功能，禁用博客，保留自定义页面
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          path: 'docs',                         // 文档目录
          routeBasePath: '/',                   // 文档作为网站首页
          sidebarPath: require.resolve('./sidebars.js'), // 侧边栏配置
          // 没有仓库，不使用 editUrl
        },
        blog: false, // 禁用博客
        pages: true, // 启用自定义页面（src/pages）
      },
    ],
  ],

  // 主题和界面配置
  themeConfig: {
    navbar: {
      title: '知识速看',
      logo: {
        alt: 'Logo',
        src: 'img/logo.svg', // 可根据需要修改为你的网站图标
      },
      items: [
        {
          to: '/', label: '首页', position: 'left',
        },
        // 如需添加更多导航项，可在此追加
      ],
    },

    footer: {
      style: 'dark',
      copyright: `© ${new Date().getFullYear()} 知识速看`,
    },

    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
    },

    sidebar: {
      autoCollapseCategories: true, // 同级分类自动折叠
      hideable: true,               // 用户可手动折叠侧边栏
    },
  },
};

export default config;

错误链接处理

值	含义说明
throw	构建时遇到断链会直接抛出错误并终止构建
warn	构建时输出警告，但不会中止构建
ignore	忽略断链（不建议使用，可能造成发布后 404）

其他

blog 功能没有那么好用，增加复杂度，所以我关了。要分享 Github 开源仓库见官网配置示例。

sidebar.js 配置

sidebars.js

/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
  docs: [
    {
      type: 'autogenerated',
      dirName: '.', // 从 docs 根目录开始自动生成
    },
  ],
};

export default sidebars;

sidebar.js 见官方配置，官方提供的这个配置文件太难用了。如果有几百篇文档，几十个目录，采用手动编写目录的方式根本是浪费时间。要么使用一个 sidebar，采用上述示例自动生成 sidebar，要么自己编写 JavaScript 脚本来替代 sidebar.js ，根据目录层级自动生成多个 sidebar 和顶部导航栏。