name: docusaurus description: 深度集成Docusaurus用于文档站点开发。配置项目、管理侧边栏、版本控制、国际化、开发插件，并为基于React的文档优化构建。 allowed-tools: Read, Write, Edit, Bash, Glob, Grep backlog-id: SK-002 metadata: author: babysitter-sdk version: “1.0.0”

Docusaurus 技能

深度集成Docusaurus用于文档站点开发。

能力

生成Docusaurus项目配置
创建和管理侧边栏结构（sidebars.js）
配置版本控制和国际化（i18n）
开发自定义Docusaurus插件
MDX组件创建与集成
构建优化与调试
Algolia DocSearch配置
主题定制

使用场景

在以下情况调用此技能：

设置新的Docusaurus文档站点
配置侧边栏和导航
实现版本化文档
添加国际化（i18n）支持
创建自定义插件或主题

输入参数

参数	类型	必填	描述
action	string	是	操作类型：init（初始化）、configure（配置）、sidebar（侧边栏）、version（版本）、i18n（国际化）、plugin（插件）
projectPath	string	是	Docusaurus项目路径
config	object	否	配置选项
version	string	否	版本标签
locale	string	否	语言区域代码

输入示例

{
  "action": "configure",
  "projectPath": "./docs-site",
  "config": {
    "title": "我的文档",
    "tagline": "我的产品开发者文档",
    "url": "https://docs.example.com",
    "organizationName": "my-org",
    "projectName": "my-project"
  }
}

项目配置

docusaurus.config.js

// @ts-check
const { themes } = require('prism-react-renderer');

/** @type {import('@docusaurus/types').Config} */
const config = {
  title: '我的文档',
  tagline: '我的产品开发者文档',
  favicon: 'img/favicon.ico',

  url: 'https://docs.example.com',
  baseUrl: '/',

  organizationName: 'my-org',
  projectName: 'my-project',

  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',

  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'ja'],
  },

  presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: './sidebars.js',
          editUrl: 'https://github.com/my-org/my-project/edit/main/',
          showLastUpdateTime: true,
          showLastUpdateAuthor: true,
          versions: {
            current: {
              label: 'Next',
              path: 'next',
            },
          },
        },
        blog: {
          showReadingTime: true,
          editUrl: 'https://github.com/my-org/my-project/edit/main/',
        },
        theme: {
          customCss: './src/css/custom.css',
        },
      }),
    ],
  ],

  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      image: 'img/social-card.jpg',
      navbar: {
        title: '我的项目',
        logo: {
          alt: '我的项目Logo',
          src: 'img/logo.svg',
        },
        items: [
          {
            type: 'docSidebar',
            sidebarId: 'tutorialSidebar',
            position: 'left',
            label: '文档',
          },
          {
            type: 'docsVersionDropdown',
            position: 'right',
          },
          {
            type: 'localeDropdown',
            position: 'right',
          },
          {
            href: 'https://github.com/my-org/my-project',
            label: 'GitHub',
            position: 'right',
          },
        ],
      },
      footer: {
        style: 'dark',
        links: [
          {
            title: '文档',
            items: [
              { label: '快速开始', to: '/docs/intro' },
              { label: 'API参考', to: '/docs/api' },
            ],
          },
          {
            title: '社区',
            items: [
              { label: 'Discord', href: 'https://discord.gg/example' },
              { label: 'Twitter', href: 'https://twitter.com/example' },
            ],
          },
        ],
        copyright: `版权所有 ${new Date().getFullYear()} 我的项目。`,
      },
      prism: {
        theme: themes.github,
        darkTheme: themes.dracula,
        additionalLanguages: ['bash', 'json', 'yaml'],
      },
      algolia: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_SEARCH_API_KEY',
        indexName: 'my-project',
        contextualSearch: true,
      },
    }),
};

module.exports = config;

侧边栏配置

sidebars.js

/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
  tutorialSidebar: [
    'intro',
    {
      type: 'category',
      label: '快速开始',
      collapsed: false,
      items: [
        'getting-started/installation',
        'getting-started/quick-start',
        'getting-started/configuration',
      ],
    },
    {
      type: 'category',
      label: '指南',
      items: [
        'guides/authentication',
        'guides/api-usage',
        {
          type: 'category',
          label: '高级',
          items: [
            'guides/advanced/caching',
            'guides/advanced/performance',
          ],
        },
      ],
    },
    {
      type: 'category',
      label: 'API参考',
      link: {
        type: 'generated-index',
        title: 'API参考',
        description: '完整的API文档',
      },
      items: [
        'api/client',
        'api/authentication',
        'api/resources',
      ],
    },
    {
      type: 'link',
      label: 'GitHub',
      href: 'https://github.com/my-org/my-project',
    },
  ],
};

module.exports = sidebars;

自定义组件

标签页组件

// src/components/CodeTabs.jsx
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import CodeBlock from '@theme/CodeBlock';

export function CodeTabs({ children, labels = ['JavaScript', 'Python', 'cURL'] }) {
  return (
    <Tabs groupId="code-examples">
      {labels.map((label, index) => (
        <TabItem key={label} value={label.toLowerCase()} label={label}>
          <CodeBlock language={label.toLowerCase()}>
            {children[index]}
          </CodeBlock>
        </TabItem>
      ))}
    </Tabs>
  );
}

API端点组件

// src/components/ApiEndpoint.jsx
import React from 'react';
import styles from './ApiEndpoint.module.css';

export function ApiEndpoint({ method, path, description }) {
  const methodColors = {
    GET: '#61affe',
    POST: '#49cc90',
    PUT: '#fca130',
    DELETE: '#f93e3e',
    PATCH: '#50e3c2',
  };

  return (
    <div className={styles.endpoint}>
      <span
        className={styles.method}
        style={{ backgroundColor: methodColors[method] }}
      >
        {method}
      </span>
      <code className={styles.path}>{path}</code>
      <p className={styles.description}>{description}</p>
    </div>
  );
}

版本控制

创建版本

# 创建版本快照
npm run docusaurus docs:version 1.0.0

# 版本化后的项目结构
docs/
├── intro.md              # 当前（next）版本
├── getting-started/
versioned_docs/
├── version-1.0.0/
│   ├── intro.md
│   └── getting-started/
versioned_sidebars/
├── version-1.0.0-sidebars.json
versions.json

versions.json

[
  "2.0.0",
  "1.1.0",
  "1.0.0"
]

国际化（i18n）

翻译结构

i18n/
├── en/
│   └── docusaurus-plugin-content-docs/
│       └── current/
│           └── intro.md
├── es/
│   └── docusaurus-plugin-content-docs/
│       └── current/
│           └── intro.md
└── ja/
    └── docusaurus-plugin-content-docs/
        └── current/
            └── intro.md

写入翻译命令

# 生成翻译文件
npm run write-translations -- --locale es

# 启动特定语言的开发服务器
npm run start -- --locale es

自定义插件

插件模板

// plugins/my-plugin/index.js
module.exports = function myPlugin(context, options) {
  return {
    name: 'my-plugin',

    async loadContent() {
      // 加载自定义内容
      return { /* content */ };
    },

    async contentLoaded({ content, actions }) {
      const { addRoute, createData } = actions;

      // 创建自定义路由
      addRoute({
        path: '/my-custom-page',
        component: '@site/src/pages/MyPage.jsx',
        exact: true,
      });
    },

    configureWebpack(config, isServer, utils) {
      // 修改webpack配置
      return {
        resolve: {
          alias: {
            '@custom': path.resolve(__dirname, 'src'),
          },
        },
      };
    },
  };
};

Algolia DocSearch

algolia.config.json

{
  "index_name": "my-project",
  "start_urls": [
    "https://docs.example.com/"
  ],
  "sitemap_urls": [
    "https://docs.example.com/sitemap.xml"
  ],
  "selectors": {
    "lvl0": ".menu__link--active",
    "lvl1": "article h1",
    "lvl2": "article h2",
    "lvl3": "article h3",
    "lvl4": "article h4",
    "content": "article p, article li"
  }
}

工作流程

初始化项目 - 创建新的Docusaurus站点
配置 - 设置docusaurus.config.js
结构化内容 - 组织文档和侧边栏
添加组件 - 创建自定义MDX组件
配置搜索 - 设置Algolia DocSearch
添加版本控制 - 创建版本快照
部署 - 构建并部署到托管平台

依赖项

{
  "dependencies": {
    "@docusaurus/core": "^3.0.0",
    "@docusaurus/preset-classic": "^3.0.0",
    "@mdx-js/react": "^3.0.0",
    "prism-react-renderer": "^2.0.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}

CLI命令

# 创建新项目
npx create-docusaurus@latest my-docs classic

# 启动开发服务器
npm run start

# 生产环境构建
npm run build

# 创建版本
npm run docusaurus docs:version 1.0.0

# 生成翻译
npm run write-translations -- --locale es

# 部署到GitHub Pages
npm run deploy

最佳实践

使用MDX实现交互式组件
为稳定版本实现版本控制
配置搜索以提高可发现性
添加编辑链接以支持社区贡献
使用提示框进行标注
使用ideal-image优化图片
启用最后更新时间戳

参考

Docusaurus: https://docusaurus.io/
MDX: https://mdxjs.com/
Algolia DocSearch: https://docsearch.algolia.com/
Prism: https://prismjs.com/

目标流程

docs-as-code-pipeline.js
docs-versioning.js
interactive-tutorials.js
knowledge-base-setup.js