Agregar o Actualizar complementos

Esta guía explica cómo agregar nuevos Capacitor complementos al sitio web de Capgo o actualizar la documentación de complementos existentes. Esto es útil para contribuyentes, mantenedores y agentes de inteligencia artificial que ayudan a mantener la documentación.

Resumen

Al agregar un nuevo complemento al ecosistema de Capgo, debe actualizar varios archivos y ubicaciones en el sitio web para asegurarse de que el complemento aparece correctamente en todos los lugares relevantes:

1. Configuración de la lista de complementos - Agregar metadatos del complemento a la lista maestra
2. Página de índice de complementos - Agregar complemento a la página de lista de complementos categorizada
3. Navegación en el lateral Agregar plugin al menú de documentación
4. Documentación del complemento - Crea páginas de visión general y de inicio
5. Tutoría de Plugin - Crea una tutoría integral

Ubicaciones de Archivos

Archivos Clave para Actualizar

Archivo	Propósito
/src/config/plugins.ts	Lista de plugins maestros con metadatos
/src/content/docs/docs/plugins/index.mdx	Página de índice de plugins con categorías
/astro.config.mjs	Configuración de navegación del menú lateral
/src/content/docs/docs/plugins/[plugin-name]/	Directorio de documentación de plugins
/src/content/plugins-tutorials/en/	Archivos de tutoriales en inglés

Guía paso a paso

1. Agregar plugin a la lista maestra

   Abrir /src/config/plugins.ts y agregar su plugin a la actions lista:

   // 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,
   }

   Iconos disponibles: Verificar /node_modules/astro-heroicons/mini/ para iconos disponibles.

2. Agregar Plugin a la Página de Índice

   Abrir /src/content/docs/docs/plugins/index.mdx y agregue su plugin en la categoría adecuada:

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

   Categorías:

   • ⭐ Plugins Destacados
   • 📱 Plugins de Dispositivo y Sistema
   • 🎥 Plugins de Medios y Cámara
   • 🛠️ Plugins de Utilidad
   • 🤖 Plugins de Inteligencia Artificial y Medios Avanzados
   • 📍 Ubicación y Servicios de Fondo
   • 📞 Comunicación y Análisis
   • 🔐 Seguridad y Sistema
   • 📊 Características Específicas de Android
   • 📥 Descargar y Navegación

3. Agregar a Navegación de Lado

   Abrir /astro.config.mjs y agregar su plugin a la configuración del menú lateral (alrededor de la línea 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,
   }

   Los plugins se enumeran alfabéticamente en la navegación de lado.

4. Crear Directorio de Documentación del Plugin

   Crear un nuevo directorio para la documentación de tu plugin:

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

5. Crear página de visión general del plugin

   Create /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. Sección titulada “Crear guía de inicio rápido”

   Create /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. Crear archivo de tutoriales

   Crear /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]

Estructura de documentación del plugin

Archivos obligatorios

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

Archivos opcionales

Para plugins complejos, puede agregar páginas de documentación adicionales:

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

Directrices de contenido

Redactar descripciones de plugins

• Ser conciso: Mantenga las descripciones debajo de 100 caracteres
• Ser específico: Explique qué hace el plugin, no qué es
• Usar verbos de acción: Comience con verbos como “Controlar”, “Integrar”, “Habilitar”

Ejemplos buenos:

• Control la luz de dispositivo con un simple interruptor de encendido/apagado
• “Integra el chat en vivo Crisp y el soporte al cliente en tu aplicación”
• “Habilita la autenticación segura utilizando Face ID y Touch ID”

“Ejemplos malos”:

• “Un plugin para flash”
• “Este es un plugin de Crisp”
• “Plugin biométrico”

“Escribiendo Documentación”

1. Comience con la InstalaciónSiempre comienza con pasos de instalación claros
2. “Proporciona Configuración”Incluir requisitos de configuración específicos de plataforma
3. Mostrar Ejemplos de UsoIncluir ejemplos de trabajo code
4. Incluir Referencia APIDocumentar todos los métodos y parámetros
5. Agregar Ejemplos CompletosIncluir patrones de uso en el mundo real
6. Listar Mejores PrácticasCompartir consejos para un uso óptimo
7. Documentar diferencias de plataformaClarificar el comportamiento de iOS vs Android
8. Agregar Solución de Problemas: Resolver problemas comunes

Code Ejemplos

• Utilice TypeScript para todos los code ejemplos
• Incluir importaciones en la parte superior
• Agregar comentarios explicando los pasos clave
• Mostrar manejo de errores
• Demonstrar tanto el uso básico como avanzado

Checklist

Utilice esta lista de verificación al agregar un nuevo plugin:

• Plugin agregado a /src/config/plugins.ts
• Seleccionó el icono adecuado de Heroicons
• Agregó el plugin a /src/content/docs/docs/plugins/index.mdx bajo la categoría correcta
• Agregó entrada en el menú lateral en /astro.config.mjs
• Creó el directorio de documentación del plugin
• Creó index.mdx la página de resumen
• Creó getting-started.mdx la guía
• Creó tutoriales en /src/content/plugins-tutorials/en/
• Incluyó instrucciones de instalación
• Documentó la configuración de iOS
• Documentación de configuración de Android
• Se proporcionan ejemplos de uso
• Agregado referencia a API
• Incluido ejemplo completo y funcional
• Se listan las mejores prácticas
• Agregadas notas específicas de plataforma
• Se han probado todos los enlaces correctamente

Referencia de iconos

Iconos comunes utilizados para plugins (desde astro-heroicons/mini/):

Icono	Uso de caso
BoltIcon	Luz, potencia, energía
CameraIcon	Cámara, foto, video
ChatBubbleLeftIcon	Chat, mensajería, comunicación
FingerPrintIcon	Biometría, seguridad, autenticación
MapPinIcon	Ubicación, geolocalización, mapas
SpeakerWaveIcon	Audio, sonido, música
VideoCameraIcon	Video, grabación, streaming
CreditCardIcon	Pagos, compras
PlayCircleIcon	Reproductores de medios, reproductores de video
SignalIcon	Conectividad, red, beacon
RadioIcon	Beacon, difusión, inalámbrico
ChatBubbleOvalLeftIcon	Redes sociales, WeChat

Actualizando Plugins Existentes

Cuando se actualice un plugin existente:

1. Actualizar números de versión en la documentación
2. Agregar guías de migración si existen cambios disruptivos
3. Actualizar la referencia a API con nuevos métodos
4. Agregar nuevos ejemplos para nuevas características
5. Actualizar requisitos de plataforma si se ha cambiado
6. Revisar las mejores prácticas basado en nuevas características
7. Mantener el tutorial actualizado con los últimos API

Rutas de idioma

Escriba y revise la documentación de plugins en inglés. Los caminos localizados se generan mediante los metadatos del sitio y se traducen en la nube por el trabajador de traducción.

Pruebas de cambios

Después de agregar o actualizar la documentación del complemento:

1. Construir el sitio localmente:

   bun run build

2. Comprobar errores:

   • Verificar que todos los enlaces funcionen
   • Asegúrese de que las imágenes se carguen correctamente
   • Confirmar que los ejemplos de code son válidos
   • Probar que la navegación funciona

3. Previsualizar el sitio:

   bun run dev

4. Verificar que tu plugin aparece:

   • Comprobar la página de lista de plugins
   • Verificar navegación lateral
   • Probar todas las páginas de documentación
   • Confirmar que la página de tutorial funciona

Pitfalls comunes

Cuidado

Evite estos errores comunes:

1. Olvidar sincronizar: Siempre ejecutar bunx cap sync en ejemplos
2. Nomenclatura inconsistente: Utiliza el mismo nombre de plugin en todas partes
3. Configuración de plataforma faltante: Documenta tanto la configuración de iOS como Android
4. Enlaces rotos: Utiliza enlaces relativos y verifica que funcionen
5. Falta de manejo de errores: Muestra siempre try-catch en los ejemplos
6. Importaciones faltantes: Incluye todas las importaciones necesarias en los ejemplos
7. Descripciones poco claras: Sé específico sobre qué hace el plugin

Obtener Ayuda

Si necesita ayuda para agregar o actualizar la documentación del plugin:

• Discord: Únete a nuestra comunidad de Discord
• GitHub: Abra un problema en el repositorio del sitio web
• Email: Contacte al equipo en soporte@capgo.app

Ejemplos

Para referencia, consulte estos plugins bien documentados:

• Actualizador: /src/content/docs/docs/plugins/updater/ (plugin complejo con varias páginas)
• Flash: /src/content/docs/docs/plugins/flash/ (plugin simple, buen ejemplo de inicio)
• Inicio de Sesión Social: /src/content/docs/docs/plugins/social-login/ Plugin con sub-páginas

Summary

Agregar un complemento al Capgo documentación implica:

1. Agregar metadatos a la configuración principal
2. Agregar el complemento a la página de índice categorizada
3. Configurando la navegación lateral
4. Creando páginas de documentación exhaustivas
5. Escribiendo un tutorial detallado
6. Probando todos los cambios localmente

Siguiendo esta guía, aseguras que los complementos estén consistentemente documentados y sean fácilmente descubribles por los usuarios.

Sigue adelante desde Agregar o Actualizar Complementos

Si estás utilizando Agregar o Actualizar Complementos para planificar el trabajo de complementos nativos, conecta con Capgo Directorio de Complementos para el flujo de trabajo del producto en el directorio de plugins Capgo Capacitor Plugins por Capgo para el detalle de implementación en Capacitor Plugins por Capgo Alternativas de plugins de Ionic Enterprise para el flujo de trabajo del producto en Ionic Enterprise Plugin Alternatives, Capgo Compilaciones nativas para el flujo de trabajo del producto en Capgo Compilaciones nativas, y Capacitor Plugins: Lo que debes saber para el contexto práctico en Capacitor Plugins: Lo que debes saber.