添加或更新插件

本指南说明如何将新的 Capacitor 插件添加到 Capgo 网站或更新现有插件文档。这对贡献者、维护者和帮助维护文档的 AI 代理很有用。

概述

在将新插件添加到 Capgo 生态系统时，您需要更新网站上的多个文件和位置，以确保插件正确显示在所有相关位置：

插件列表配置 - 将插件元数据添加到主列表
插件索引页面 - 将插件添加到分类插件列表页面
侧边栏导航 - 将插件添加到文档侧边栏
插件文档 - 创建概述和入门页面
插件教程 - 创建全面的教程

文件位置

要更新的关键文件

文件	用途
`/src/config/plugins.ts`	包含元数据的主插件列表
`/src/content/docs/docs/plugins/index.mdx`	包含分类的插件索引页面
`/astro.config.mjs`	侧边栏导航配置
`/src/content/docs/docs/plugins/[plugin-name]/`	插件文档目录
`/src/content/plugins-tutorials/en/`	英文教程文件

分步指南

将插件添加到主列表

打开 /src/config/plugins.ts 并将您的插件添加到 actions 数组：

// 首先，导入适当的 Heroicon
import YourIconName from 'astro-heroicons/mini/IconName.astro'

// 然后添加到 actions 数组
{
  name: '@capgo/your-plugin-name',
  author: 'github.com/Cap-go',
  description: '插件功能的简短描述',
  href: 'https://github.com/Cap-go/your-plugin-name/',
  title: '显示名称',
  icon: YourIconName,
}

可用图标: 检查 /node_modules/astro-heroicons/mini/ 以查看可用图标。

将插件添加到索引页面
Section titled “将插件添加到索引页面”

打开 /src/content/docs/docs/plugins/index.mdx 并将您的插件添加到适当的类别下：
```
<LinkCard
  title="您的插件名称"
  description="插件功能的简短描述"
  href="/docs/plugins/your-plugin-name/"
/>
```
类别:
- ⭐ 特色插件
- 📱 设备和系统插件
- 🎥 媒体和相机插件
- 🛠️ 实用工具插件
- 🤖 AI 和高级媒体
- 📍 位置和后台服务
- 📞 通信和分析
- 🔐 安全和系统
- 📊 Android 特定功能
- 📥 下载和导航

添加到侧边栏导航

打开 /astro.config.mjs 并将您的插件添加到侧边栏配置（大约第 540 行）：

{
  label: '您的插件名称',
  items: [
    { label: '概述', link: '/docs/plugins/your-plugin-name/' },
    { label: '入门', link: '/docs/plugins/your-plugin-name/getting-started' },
  ],
  collapsed: true,
}

插件在侧边栏中按字母顺序列出。

创建插件文档目录
Section titled “创建插件文档目录”

为您的插件文档创建一个新目录：
Terminal window
```
mkdir -p /src/content/docs/docs/plugins/your-plugin-name/
```

创建插件概述页面

创建 /src/content/docs/docs/plugins/your-plugin-name/index.mdx：

---
title: "@capgo/your-plugin-name"
description: 插件用途的简短描述
tableOfContents: false
next: false
prev: false
sidebar:
  order: 1
  label: "介绍"
hero:
  tagline: 详细说明插件功能的标语
  image:
    file: ~public/your-plugin-icon.svg
  actions:
    - text: 开始使用
      link: /docs/plugins/your-plugin-name/getting-started/
      icon: right-arrow
      variant: primary
    - text: Github
      link: https://github.com/Cap-go/your-plugin-name/
      icon: external
      variant: minimal
---

import { Card, CardGrid } from '@astrojs/starlight/components';

<CardGrid stagger>
  <Card title="功能 1" icon="puzzle">
    第一个关键功能的描述
  </Card>
  <Card title="功能 2" icon="rocket">
    第二个关键功能的描述
  </Card>
  <Card title="跨平台" icon="puzzle">
    适用于 iOS 和 Android 📱
  </Card>
  <Card title="全面的文档" icon="open-book">
    查看[文档](/docs/plugins/your-plugin-name/getting-started/)以掌握插件。
  </Card>
</CardGrid>

创建入门指南

创建 /src/content/docs/docs/plugins/your-plugin-name/getting-started.mdx：

---
title: 入门
description: 了解如何在您的 Capacitor 应用中安装和使用该插件。
sidebar:
  order: 2
---

import { Steps } from '@astrojs/starlight/components';
import { PackageManagers } from 'starlight-package-managers'

<Steps>
1. **安装软件包**
   <PackageManagers pkg="@capgo/your-plugin-name" pkgManagers={['npm', 'pnpm', 'yarn', 'bun']} />

2. **与原生项目同步**
   <PackageManagers type="exec" pkg="cap" args="sync" pkgManagers={['npm', 'pnpm', 'yarn', 'bun']} />
</Steps>

## 配置

### iOS 配置
[iOS 特定设置说明]

### Android 配置
[Android 特定设置说明]

## 使用

[基本使用示例]

## API 参考

[详细的 API 文档]

## 完整示例

[完整的工作示例]

## 最佳实践

[推荐的实践和提示]

## 平台说明

[平台特定说明和限制]

创建教程文件

创建 /src/content/plugins-tutorials/en/your-plugin-name.md：

---
locale: en
---
# 使用 @capgo/your-plugin-name 包

`@capgo/your-plugin-name` 包[简短描述]。在本教程中，我们将指导您在 Ionic Capacitor 应用中安装、配置和使用此包。

## 安装

[安装步骤]

## 配置

[iOS 和 Android 的配置步骤]

## API 使用

[详细的 API 使用示例]

## 完整示例

[完整的工作示例]

## 最佳实践

[提示和最佳实践]

## 故障排除

[常见问题和解决方案]

## 结论

[摘要和其他资源的链接]

插件文档结构

必需文件

src/content/docs/docs/plugins/your-plugin-name/
├── index.mdx           # 包含 hero 和功能卡的概述页面
└── getting-started.mdx # 安装和使用指南

src/content/plugins-tutorials/en/
└── your-plugin-name.md # 全面的教程

可选文件

对于复杂的插件，您可以添加其他文档页面：

src/content/docs/docs/plugins/your-plugin-name/
├── index.mdx
├── getting-started.mdx
├── api-reference.mdx   # 详细的 API 文档
├── examples.mdx        # 其他示例
├── troubleshooting.mdx # 故障排除指南
└── migrations.mdx      # 迁移指南

内容指南

编写插件描述

简洁: 保持描述在 100 个字符以下
具体: 解释插件的功能，而不是它是什么
使用动词: 以”控制”、“集成”、“启用”等动词开头

好的示例:

“使用简单的开/关切换控制设备手电筒和火炬”
“将 Crisp 实时聊天和客户支持集成到您的应用中”
“使用 Face ID 和 Touch ID 启用安全身份验证”

不好的示例:

“闪光灯的插件”
“这是一个 Crisp 插件”
“生物识别插件”

编写文档

从安装开始: 始终以清晰的安装步骤开始
提供配置: 包括平台特定的设置要求
显示使用示例: 提供工作代码示例
包括 API 参考: 记录所有方法和参数
添加完整示例: 显示真实世界的使用模式
列出最佳实践: 分享最佳使用技巧
记录平台差异: 阐明 iOS 与 Android 的行为
添加故障排除: 解决常见问题

代码示例

对所有代码示例使用 TypeScript
在顶部包含导入
添加解释关键步骤的注释
显示错误处理
演示基本和高级用法

检查清单

添加新插件时使用此检查清单：

图标参考

插件常用的图标（来自 astro-heroicons/mini/）：

图标	用例
`BoltIcon`	闪光灯、电源、能量
`CameraIcon`	相机、照片、视频
`ChatBubbleLeftIcon`	聊天、消息、通信
`FingerPrintIcon`	生物识别、安全、身份验证
`MapPinIcon`	位置、地理定位、地图
`SpeakerWaveIcon`	音频、声音、音乐
`VideoCameraIcon`	视频、录制、流媒体
`CreditCardIcon`	支付、购买
`PlayCircleIcon`	媒体播放器、视频播放器
`SignalIcon`	连接、网络、信标
`RadioIcon`	信标、广播、无线
`ChatBubbleOvalLeftIcon`	社交媒体、微信

更新现有插件

更新现有插件时：

更新文档中的版本号
如果存在重大更改，添加迁移指南
使用新方法更新 API 参考
为新功能添加新示例
如果更改了平台要求，则更新
根据新功能修改最佳实践
使用最新 API 保持教程最新

多语言支持

该网站支持多种语言。创建英文文档后：

运行翻译脚本：
Terminal window
```
bun run plugins:translate_all
```
查看生成的翻译：
- /src/content/plugins-tutorials/de/ (德语)
- /src/content/plugins-tutorials/es/ (西班牙语)
- /src/content/plugins-tutorials/fr/ (法语)
- /src/content/plugins-tutorials/it/ (意大利语)
- /src/content/plugins-tutorials/ja/ (日语)
- /src/content/plugins-tutorials/ko/ (韩语)
- /src/content/plugins-tutorials/id/ (印度尼西亚语)

测试您的更改

添加或更新插件文档后：

在本地构建网站:
Terminal window
```
npm run build
```
检查错误:
- 验证所有链接是否有效
- 确保图像正确加载
- 确认代码示例有效
- 测试导航是否正常
预览网站:
Terminal window
```
npm run dev
```
验证您的插件是否显示:
- 检查插件列表页面
- 验证侧边栏导航
- 测试所有文档页面
- 确认教程页面有效

常见陷阱

获取帮助

如果您在添加或更新插件文档时需要帮助：

Discord: 加入我们的 Discord 社区
GitHub: 在网站仓库上提出问题
电子邮件: 通过 support@capgo.app 联系团队

示例

作为参考，请查看这些记录良好的插件：

Updater: /src/content/docs/docs/plugins/updater/ (包含多个页面的复杂插件)
Flash: /src/content/docs/docs/plugins/flash/ (简单插件，良好的入门示例)
Social Login: /src/content/docs/docs/plugins/social-login/ (包含子页面的插件)

摘要

将插件添加到 Capgo 文档涉及：

将元数据添加到主配置
将插件添加到分类索引页面
配置侧边栏导航
创建全面的文档页面
编写详细的教程
在本地测试所有更改

通过遵循本指南，您可以确保插件被一致地记录并且用户易于发现。