添加或更新插件

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

概述

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

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

文件位置

关键文件更新

文件	目的
/src/config/plugins.ts	context:Capgo营销网站,作用:短UI标签或导航项,信息键`subprocessors_table_purpose` (子处理器表目的)
/src/content/docs/docs/plugins/index.mdx	主插件列表
/astro.config.mjs	插件索引页
/src/content/docs/docs/plugins/[plugin-name]/	侧边栏导航配置
/src/content/plugins-tutorials/en/	插件文档目录

英文教程文件

1. 标题：逐步指南

   标题：添加插件到主列表 /src/config/plugins.ts 并且将您的插件添加到 actions 数组:

   // First, import an appropriate Heroicon
   import YourIconName from 'astro-heroicons/mini/IconName.astro'
   
   // Then add to the actions array
   {
     name: '@capgo/your-plugin-name',
     author: 'github.com/Cap-go',
     description: 'Brief description of what the plugin does',
     href: 'https://github.com/Cap-go/your-plugin-name/',
     title: 'Display Name',
     icon: YourIconName,
   }

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

2. 将插件添加到首页

   打开 /src/content/docs/docs/plugins/index.mdx 并在适当的类别下添加您的插件:

   <LinkCard
     title="Your Plugin Name"
     description="Brief description of what the plugin does"
     href="/docs/plugins/your-plugin-name/"
   />

   类别:

   • ⭐推荐插件
   • 📱设备和系统插件
   • 🎥媒体和摄像头插件
   • 🛠️工具插件
   • 🤖人工智能和高级媒体
   • 📍位置和后台服务
   • 📞通信和分析
   • 🔐安全和系统
   • 📊安卓特定功能
   • 📥下载和导航

3. 添加到侧边栏导航

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

   {
     label: 'Your Plugin Name',
     items: [
       { label: 'Overview', link: '/docs/plugins/your-plugin-name/' },
       { label: 'Getting started', link: '/docs/plugins/your-plugin-name/getting-started' },
     ],
     collapsed: true,
   }

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

4. 创建插件文档目录

   为您的插件文档创建一个新目录：

   mkdir -p /src/content/docs/docs/plugins/your-plugin-name/

5. 创建插件概览页面

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

   ---
   title: "@capgo/your-plugin-name"
   description: Brief description of the plugin's purpose
   tableOfContents: false
   next: false
   prev: false
   sidebar:
     order: 1
     label: "Introduction"
   hero:
     tagline: Detailed tagline explaining what the plugin does
     image:
       file: ~public/your-plugin-icon.svg
     actions:
       - text: Get started
         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="Feature 1" icon="puzzle">
       Description of first key feature
     </Card>
     <Card title="Feature 2" icon="rocket">
       Description of second key feature
     </Card>
     <Card title="Cross-platform" icon="puzzle">
       Works on both iOS and Android 📱
     </Card>
     <Card title="Comprehensive Documentation" icon="open-book">
       Check the [Documentation](/docs/plugins/your-plugin-name/getting-started/) to master the plugin.
     </Card>
   </CardGrid>

6. 创建开始使用指南

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

   ---
   title: Getting Started
   description: Learn how to install and use the plugin in your Capacitor app.
   sidebar:
     order: 2
   ---
   
   import { Steps } from '@astrojs/starlight/components';
   import { PackageManagers } from 'starlight-package-managers'
   
   <Steps>
   1. **Install the package**
      <PackageManagers pkg="@capgo/your-plugin-name" pkgManagers={['npm', 'pnpm', 'yarn', 'bun']} />
   
   2. **Sync with native projects**
      <PackageManagers type="exec" pkg="cap" args="sync" pkgManagers={['npm', 'pnpm', 'yarn', 'bun']} />
   </Steps>
   
   ## Configuration
   
   ### iOS Configuration
   [iOS-specific setup instructions]
   
   ### Android Configuration
   [Android-specific setup instructions]
   
   ## Usage
   
   [Basic usage examples]
   
   ## API Reference
   
   [Detailed API documentation]
   
   ## Complete Example
   
   [Full working example]
   
   ## Best Practices
   
   [Recommended practices and tips]
   
   ## Platform Notes
   
   [Platform-specific notes and limitations]

7. 创建教程文件

   复制到剪贴板 /src/content/plugins-tutorials/en/your-plugin-name.md:

   ---
   locale: en
   ---
   # Using @capgo/your-plugin-name Package
   
   The `@capgo/your-plugin-name` package [brief description]. In this tutorial, we will guide you through the installation, configuration, and usage of this package in your Ionic Capacitor app.
   
   ## Installation
   
   [Installation steps]
   
   ## Configuration
   
   [Configuration steps for iOS and Android]
   
   ## API Usage
   
   [Detailed API usage examples]
   
   ## Complete Example
   
   [Full working example]
   
   ## Best Practices
   
   [Tips and best practices]
   
   ## Troubleshooting
   
   [Common issues and solutions]
   
   ## Conclusion
   
   [Summary and links to additional resources]

插件文档结构

required files

src/content/docs/docs/plugins/your-plugin-name/
├── index.mdx           # Overview page with hero and feature cards
└── getting-started.mdx # Installation and usage guide

src/content/plugins-tutorials/en/
└── your-plugin-name.md # Comprehensive tutorial

Optional Files

对于复杂的插件，您可能需要添加额外的文档页面：

src/content/docs/docs/plugins/your-plugin-name/
├── index.mdx
├── getting-started.mdx
├── api-reference.mdx   # Detailed API documentation
├── examples.mdx        # Additional examples
├── troubleshooting.mdx # Troubleshooting guide
└── migrations.mdx      # Migration guides

内容指南

编写插件描述

• 简洁: 描述长度不超过100个字符
• 具体说明: 描述插件的功能，而不是它是什么
• 使用动词: 以“控制”，“整合”，“启用”等动词开始

好的例子:

• “使用简单的开关控制设备的闪光灯和手电筒”
• “将 Crisp 的实时聊天和客户支持整合到您的应用中”
• “使用 Face ID 和 Touch ID 启用安全认证”

坏的例子:

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

编写文档

1. 开始安装:始终以清晰的安装步骤开始
2. 提供配置:包含平台特定的设置要求
3. 展示使用示例:提供工作code示例
4. 包含API参考:记录所有方法和参数
5. 添加完整示例:展示现实世界的使用模式
6. 最佳实践列表: 提供最佳使用建议
7. 文档平台差异: 解释 iOS 与 Android 行为
8. 添加故障排除: 解决常见问题

Code 示例

• 使用 TypeScript 为所有 code 示例
• 在顶部包含导入语句
• 添加解释关键步骤的注释
• 显示错误处理
• 演示基本和高级使用

检查清单

在添加新插件时，请使用此检查清单:

• 将插件添加到 /src/config/plugins.ts
• 从Heroicons中选择了合适的图标
• 将插件添加到 /src/content/docs/docs/plugins/index.mdx 在正确的类别下
• 在 /astro.config.mjs
• 创建了插件文档目录
• 创建了 index.mdx 概述页面
• 创建了 getting-started.mdx 指南
• 创建了教程 /src/content/plugins-tutorials/en/
• 包含了安装说明
• 文档了iOS配置
• 文档了Android配置
• 提供了使用示例
• 添加了API参考
• 包含了完整的工作示例
• 列出了最佳实践
• 添加了平台特定说明
• 测试了所有链接正确工作

图标参考

插件中使用的常用图标（来自 astro-heroicons/mini/):

图标	应用场景
BoltIcon	context:Capgo解决方案营销页面。角色:短的UI标签或导航项。见于：页面解决方案/cordova-to-capacitor-ai.astro。消息键`solutions_cordova_to_capacitor_ai_table_use_case`（解决方案Cordova To Capacitor Ai表格用例）
CameraIcon	闪烁，电力，能源
ChatBubbleLeftIcon	摄像头，照片，视频
FingerPrintIcon	聊天，信息，沟通
MapPinIcon	生物识别，安全，身份验证
SpeakerWaveIcon	位置，地理位置，地图
VideoCameraIcon	音频，声音，音乐
CreditCardIcon	支付, 购买
PlayCircleIcon	媒体播放器, 视频播放器
SignalIcon	连接, 网络, 蓝牙
RadioIcon	蓝牙, 广播, 无线
ChatBubbleOvalLeftIcon	社交媒体, 微信

更新现有插件

当更新现有插件时：

1. 更新版本号 在文档中
2. 添加迁移指南 如果存在破坏性更改
3. 更新 API 参考 使用新方法
4. 添加新示例 为新功能添加示例
5. 更新平台要求 如果发生变化
6. 根据新功能修订最佳实践 保持教程最新
7. 使用最新的 __CAPGO_KEEP_0__ with latest API

标题为“语言路径”

在英语中编写和审阅插件文档。 本地化路径由站点元数据生成并在边缘由翻译工人翻译。

测试您的更改

在添加或更新插件文档后:

1. 本地构建站点:

   bun run build

2. 检查错误:

   • 验证所有链接正常工作
   • 确保图像正确加载
   • 确认code示例有效
   • 测试导航功能

3. 预览网站:

   bun run dev

4. 确认插件已显示:

   • 检查插件列表页面
   • 确认侧边栏导航
   • 测试所有文档页面
   • 确认教程页面正常

常见问题

注意

避免这些常见错误:

1. 忘记同步::始终运行 bunx cap sync 在示例中
2. 命名不一致::在所有地方使用相同的插件名称
3. 缺少平台配置::在iOS和Android设置中都要文档
4. 断链::使用相对链接并验证它们可用
5. 无错误处理::始终在示例中显示try-catch
6. 缺少的导入语句: 在示例中包含所有必要的导入语句
7. 不清晰的描述: 对插件的功能进行具体说明

获取帮助

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

• : 加入我们的Discord 社区 : 打开一个关于
• GitHub__CAPGO_KEEP_0__ 网站仓库
• 邮箱: 联系团队 support@capgo.app

示例

参考以下文档齐全的插件:

• 更新器: /src/content/docs/docs/plugins/updater/ (复杂插件，多页)
• 闪烁: /src/content/docs/docs/plugins/flash/ (简单插件，好用的示例)
• 社交登录: /src/content/docs/docs/plugins/social-login/ （插件及其子页面）

概要

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

1. 添加元数据到主配置
2. 将插件添加到分类索引页面
3. 配置侧边栏导航
4. 创建全面文档页面
5. 编写详细教程
6. 测试所有更改

按照本指南，您可以确保插件的文档一致且易于用户发现。

继续阅读添加或更新插件

如果您正在使用 添加或更新插件 与 Capgo 插件目录 为产品工作流程在 Capgo 插件目录中 Capacitor 插件由 Capgo 为实现细节在 Capacitor 插件由 Capgo 中 Ionic 企业插件替代品 为产品工作流程在 Ionic 企业插件替代品中 Capgo 原生构建 为产品工作流程在 Capgo 原生构建中 Capacitor 插件：您需要知道的 为 Capacitor 插件：您需要知道的提供实际上下文。