docusaurus

用途

Docusaurus Skill 用于与 Docusaurus 文档站点开发框架进行深度集成，帮助开发者完成文档站点的配置、内容组织、版本管理、国际化、插件开发与构建优化等工作。

主要能力

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

使用方式

通过传入参数调用该技能，主要参数包括：

action（字符串，必填）：操作类型，可选值为 init、configure、sidebar、version、i18n、plugin
projectPath（字符串，必填）：Docusaurus 项目路径
config（对象，可选）：配置选项
version（字符串，可选）：用于版本控制的版本标签
locale（字符串，可选）：用于 i18n 的语言代码

输入示例：

{
  "action": "configure",
  "projectPath": "./docs-site",
  "config": {
    "title": "My Documentation",
    "tagline": "Developer documentation for My Product",
    "url": "https://docs.example.com",
    "organizationName": "my-org",
    "projectName": "my-project"
  }
}

项目配置

在 docusaurus.config.js 中可配置站点标题、标语、favicon、URL、baseUrl、组织名、项目名、断链处理策略、i18n 语言列表、经典预设（docs、blog、theme）、主题配置（导航栏、页脚、代码高亮、Algolia 搜索）等。

侧边栏配置

在 sidebars.js 中可定义侧边栏结构，支持文档项、分类（category）、链接（link）以及自动生成的索引页（generated-index）。分类可设置是否默认折叠，并可嵌套子分类。

自定义组件

可创建 MDX 组件，例如代码标签页组件（CodeTabs）和 API 端点组件（ApiEndpoint），用于在文档中展示多语言代码示例和 API 接口信息。

版本控制

使用命令 npm run docusaurus docs:version 1.0.0 创建版本快照。版本化后项目结构会包含 versioned_docs、versioned_sidebars 目录以及 versions.json 文件。versions.json 中按顺序列出各版本号。

国际化（i18n）

翻译文件位于 i18n 目录下，按语言代码组织。使用 npm run write-translations -- --locale es 生成翻译文件，使用 npm run start -- --locale es 启动指定语言的开发服务器。

自定义插件

插件模板导出一个函数，接收 context 和 options 参数，返回包含 name、loadContent、contentLoaded、configureWebpack 等钩子的对象，可用于加载自定义内容、添加路由和修改 webpack 配置。

Algolia DocSearch

通过 algolia.config.json 配置索引名称、起始 URL、站点地图 URL 以及各级标题和内容的 CSS 选择器。

工作流程

初始化项目——创建新的 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 实现交互式组件
为稳定版本实施版本控制
配置搜索以提高可发现性
添加编辑链接以便社区贡献
使用 admonitions 进行提示标注
使用 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

适用场景

适用于需要搭建或维护 Docusaurus 文档站点的开发者，包括新建文档站点、配置侧边栏与导航、实现版本化文档、添加多语言支持、创建自定义插件或主题、配置 Algolia 搜索以及构建部署等场景。

限制

资料中未提供关于收费、价格、平台限制或具体效果保证的信息。