docusaurus-generator

用途

Docusaurus Generator 是一个技能，用于通过分析当前项目，使用 Docusaurus 3.x 生成终端用户文档。当用户要求创建文档、生成文档等时，可以使用此技能。

主要能力

该技能的工作流程包括：

分析项目结构，以了解需要记录的内容。
初始化一个新的 Docusaurus 3.x 项目（或使用现有项目）。
根据项目分析生成文档内容。
配置 Docusaurus 设置和主题。
构建并预览文档站点。

步骤 1：分析项目

在生成文档之前，分析项目以识别：

包结构：检查 package.json、monorepo 设置
现有文档：查找 docs/、README.md、JSDoc 注释
功能：从路由、组件、API 中识别主要功能
配置：检查揭示功能的配置文件

关键文件检查命令：

find . -name "README.md" -o -name "*.md" | head -20
ls -la docs/ 2>/dev/null
cat package.json | jq '.name, .description'

步骤 2：初始化 Docusaurus

在 docs-site/ 目录中创建一个新的 Docusaurus 3.x 项目：

npx -y create-docusaurus@latest docs-site classic --typescript

或者如果文档已存在，则跳到配置步骤。

步骤 3：生成文档内容

文档结构建议如下：

docs-site/docs/
├── intro.md                    # 入门指南
├── installation.md             # 安装指南
├── features/
│   ├── feature-1.md
│   └── feature-2.md
├── guides/
│   ├── quick-start.md
│   └── advanced-usage.md
├── configuration/
│   └── settings.md
└── faq.md

每个文档应包含正确的 frontmatter：

---
sidebar_position: 1
title: Page Title
description: Brief description for SEO
---

# Page Title

Content here...

内容指南：

面向终端用户，而非开发者
使用简单清晰的语言
为 UI 功能包含截图
在相关处添加代码示例
在相关文档之间建立链接

步骤 4：配置 Docusaurus

docusaurus.config.ts 关键配置选项示例：

import {themes as prismThemes} from 'prism-react-renderer';
import type {Config} from '@docusaurus/types';

const config: Config = {
  title: 'Project Name',
  tagline: 'Your tagline here',
  favicon: 'img/favicon.ico',
  url: 'https://your-docs-url.com',
  baseUrl: '/',
  
  // Localization
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'vi'],
  },
  
  themeConfig: {
    navbar: {
      title: 'Project Name',
      logo: {
        alt: 'Logo',
        src: 'img/logo.svg',
      },
      items: [
        {
          type: 'docSidebar',
          sidebarId: 'tutorialSidebar',
          position: 'left',
          label: 'Docs',
        },
      ],
    },
    footer: {
      style: 'dark',
      copyright: `Copyright © ${new Date().getFullYear()}`,
    },
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
    },
  },
};

export default config;

主题自定义：编辑 src/css/custom.css 进行品牌化：

:root {
  --ifm-color-primary: #2e8555;
  --ifm-color-primary-dark: #29784c;
  --ifm-color-primary-darker: #277148;
  --ifm-color-primary-darkest: #205d3b;
  --ifm-color-primary-light: #33925d;
  --ifm-color-primary-lighter: #359962;
  --ifm-color-primary-lightest: #3cad6e;
  --ifm-code-font-size: 95%;
}

[data-theme='dark'] {
  --ifm-color-primary: #25c2a0;
}

步骤 5：构建与预览

cd docs-site

# Install dependencies
npm install

# Start dev server
npm run start

# Build for production
npm run build

# Serve production build locally
npm run serve

常用插件

搜索（Algolia 或本地）

不使用 Algolia 的本地搜索：

npm install @easyops-cn/docusaurus-search-local

// docusaurus.config.ts
themes: [
  [
    '@easyops-cn/docusaurus-search-local',
    {
      hashed: true,
      language: ['en', 'vi'],
    },
  ],
],

博客

经典模板中已包含。在 docusaurus.config.ts 中配置：

blog: {
  showReadingTime: true,
  blogSidebarCount: 'ALL',
},

版本控制

npm run docusaurus docs:version 1.0.0

多语言支持

启用 i18n：

在 docusaurus.config.ts 中配置 locales
在 i18n/vi/docusaurus-plugin-content-docs/current/ 中创建翻译文档
将语言切换器添加到导航栏

navbar: {
  items: [
    {
      type: 'localeDropdown',
      position: 'right',
    },
  ],
},

翻译工作流：

# Generate translation files
npm run write-translations -- --locale vi

# Start dev server with locale
npm run start -- --locale vi

最佳实践

保持 intro 简短——用户希望快速开始
使用 admonitions 提示、警告：

:::tip
Pro tip here
:::

:::warning
Be careful about this
:::

将图片添加到 static/img/ 并引用为 /img/filename.png
使用 tabs 处理平台特定内容：

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="npm" label="npm">npm install</TabItem>
  <TabItem value="yarn" label="Yarn">yarn add</TabItem>
</Tabs>

使用 sidebars.ts 从文件夹结构自动生成侧边栏

适用场景

需要为当前项目生成终端用户文档站点
用户要求创建文档、生成文档
希望使用 Docusaurus 3.x 快速搭建文档站点

限制

资料中未明确说明该技能的具体限制、收费、价格、平台或效果。