docusaurus-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docusaurus Generator

Docusaurus生成器

This skill generates end-user documentation using Docusaurus 3.x by analyzing the current project.

本技能通过分析当前项目，使用Docusaurus 3.x生成面向终端用户的文档。

Workflow Overview

工作流概述

Analyze the project structure to understand what to document
Initialize a new Docusaurus 3.x project (or use existing)
Generate documentation content from project analysis
Configure Docusaurus settings and theme
Build & Preview the documentation site

分析项目结构，确定需要记录的内容
初始化全新的Docusaurus 3.x项目（或使用已有项目）
基于项目分析结果生成文档内容
配置Docusaurus的设置和主题
构建并预览文档站点

Step 1: Analyze Project

步骤1：分析项目

Before generating docs, analyze the project to identify:

Package structure: Check
```
package.json
```
, monorepo setup
Existing docs: Look for
```
docs/
```
,
```
README.md
```
, JSDoc comments
Features: Identify main features from routes, components, APIs
Configuration: Check for config files that reveal functionality

bash

undefined

生成文档前，先分析项目，识别以下信息：

包结构：检查
```
package.json
```
、monorepo配置
现有文档：查找
```
docs/
```
目录、
```
README.md
```
、JSDoc注释
功能特性：从路由、组件、API中识别核心功能
配置信息：检查可暴露功能的配置文件

bash

undefined

Key files to examine

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

undefined

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

undefined

Step 2: Initialize Docusaurus

步骤2：初始化Docusaurus

Create a new Docusaurus 3.x project in

docs-site/

directory:

bash

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

Or if docs already exist, skip to configuration.

在

docs-site/

目录下创建全新的Docusaurus 3.x项目：

bash

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

如果已有文档，可直接跳过本步骤进入配置环节。

Step 3: Generate Documentation Content

步骤3：生成文档内容

Documentation Structure

文档结构

Organize docs following this structure:

docs-site/docs/
├── intro.md                    # Getting started
├── installation.md             # Installation guide
├── features/
│   ├── feature-1.md
│   └── feature-2.md
├── guides/
│   ├── quick-start.md
│   └── advanced-usage.md
├── configuration/
│   └── settings.md
└── faq.md

按照以下结构组织文档：

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 Template

前置元数据模板

Every doc should have proper frontmatter:

markdown

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

每份文档都需要配置正确的前置元数据：

markdown

---
sidebar_position: 1
title: 页面标题
description: 用于SEO的简要描述
---

Page Title

页面标题

Content here...

undefined

内容在这里...

undefined

Content Guidelines

内容规范

Write for end users, not developers
Use simple, clear language
Include screenshots for UI features
Add code examples where relevant
Link between related docs

面向终端用户编写，而非开发者
使用简洁清晰的语言
UI功能需包含截图
相关位置补充代码示例
相关文档之间互相添加跳转链接

Step 4: Configure Docusaurus

步骤4：配置Docusaurus

docusaurus.config.ts

Key configuration options:

typescript

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;

核心配置项：

typescript

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

const config: Config = {
  title: '项目名称',
  tagline: '你的项目标语在这里',
  favicon: 'img/favicon.ico',
  url: 'https://your-docs-url.com',
  baseUrl: '/',
  
  // 国际化配置
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'vi'],
  },
  
  themeConfig: {
    navbar: {
      title: '项目名称',
      logo: {
        alt: 'Logo',
        src: 'img/logo.svg',
      },
      items: [
        {
          type: 'docSidebar',
          sidebarId: 'tutorialSidebar',
          position: 'left',
          label: '文档',
        },
      ],
    },
    footer: {
      style: 'dark',
      copyright: `Copyright © ${new Date().getFullYear()}`,
    },
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
    },
  },
};

export default config;

Theme Customization

主题自定义

Edit

src/css/custom.css

for branding:

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;
}

编辑

src/css/custom.css

来适配品牌风格：

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;
}

Step 5: Build & Preview

步骤5：构建与预览

bash

cd docs-site

bash

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

undefined

npm run serve

undefined

Common Plugins

常用插件

Search (Algolia or local)

搜索功能（Algolia或本地搜索）

For local search without Algolia:

bash

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

typescript

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

无需Algolia的本地搜索方案：

bash

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

typescript

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

Blog

博客功能

Already included in classic template. Configure in

docusaurus.config.ts

typescript

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

经典模板已默认包含博客功能，可在

docusaurus.config.ts

中配置：

typescript

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

Versioning

版本管理

bash

npm run docusaurus docs:version 1.0.0

bash

npm run docusaurus docs:version 1.0.0

Multi-language Support

多语言支持

Enable i18n

开启国际化

Configure locales in
```
docusaurus.config.ts
```

Create translated docs in

i18n/vi/docusaurus-plugin-content-docs/current/

Add locale switcher to navbar

typescript

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

在
```
docusaurus.config.ts
```
中配置语言项

在

i18n/vi/docusaurus-plugin-content-docs/current/

路径下存放翻译后的文档

在导航栏添加语言切换器

typescript

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

Translation workflow

翻译工作流

bash

undefined

bash

undefined

Generate translation files

生成翻译文件

npm run write-translations -- --locale vi

Start dev server with locale

启动对应语言的开发服务器

npm run start -- --locale vi

undefined

npm run start -- --locale vi

undefined

Best Practices

最佳实践

Keep intro short - Users want to get started quickly

Use admonitions for tips, warnings:

markdown

:::tip
Pro tip here
:::

:::warning
Be careful about this
:::

Add images to
```
static/img/
```
and reference as
```
/img/filename.png
```

Use tabs for platform-specific content:

jsx

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>

Auto-generate sidebar from folder structure using
```
sidebars.ts
```

简介尽量简短 - 用户希望快速上手

使用提示块展示小贴士、警告信息：

markdown

:::tip
实用小贴士在这里
:::

:::warning
请注意相关风险
:::

将图片存放到
```
static/img/
```
目录下，引用路径为
```
/img/filename.png
```

使用标签页展示不同平台对应的内容：

jsx

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
```
**基于文件夹结构自动生成侧边栏