Agregar o actualizar complementos

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

Descripción general

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

1. Configuración de la lista de complementos: agregue metadatos de complementos a la lista maestra
2. Página de índice de complementos: agregue el complemento a la página de listado de complementos categorizados
3. Navegación en la barra lateral: agregue un complemento a la barra lateral de documentación
4. Documentación del complemento: cree páginas de descripción general y de introducción
5. Tutorial del complemento: cree un tutorial completo

Ubicaciones de archivos

Archivos clave para actualizar

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

Guía paso a paso

1. Agregar complemento a la lista maestra

   Abra /src/config/plugins.ts y agregue su complemento a la matriz 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,
   }

   Iconos disponibles: consulte /node_modules/astro-heroicons/mini/ para ver los íconos disponibles.

2. Agregar complemento a la página de índice

   Abra /src/content/docs/docs/plugins/index.mdx y agregue su complemento en la categoría apropiada:

   <LinkCard
     title="El nombre de tu complemento"
     description="Brief description of what the plugin does"
     href="/docs/plugins/your-plugin-name/"
   />

   Categorías:

   • ⭐ Complementos destacados
   • 📱 Complementos de dispositivo y sistema
   • 🎥 Complementos de cámara y medios
   • 🛠️ Complementos de utilidad
   • 🤖 IA y medios avanzados
   • 📍 Servicios de ubicación y antecedentes
   • 📞 Comunicación y análisis
   • 🔐 Seguridad y sistema
   • 📊 Android-Características específicas
   • 📥 Descarga y navegación

3. Agregar a la navegación de la barra lateral

   Abra /astro.config.mjs y agregue su complemento a la configuración de la barra 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 complementos se enumeran alfabéticamente en la barra lateral.

4. Crear directorio de documentación de complementos

   Cree un nuevo directorio para la documentación de su complemento:

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

5. Crear página de descripción general del complemento

   Cree /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="Característica 1" icon="puzzle">
       Description of first key feature
     </Card>
     <Card title="Característica 2" icon="rocket">
       Description of second key feature
     </Card>
     <Card title="Cross-platform" icon="puzzle">
       Works on both iOS and Android 📱
     </Card>
     <Card title="Documentación completa" icon="open-book">
       Check the [Documentation](/docs/plugins/your-plugin-name/getting-started/) to master the plugin.
     </Card>
   </CardGrid>

6. Crear una guía de introducción

   Cree /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 tutorial

   Cree /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 complemento

Archivos requeridos

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 complementos 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

Pautas de contenido

Escribir descripciones de complementos

• Sea conciso: mantenga las descripciones de menos de 100 caracteres
• Sea específico: explique qué hace el complemento, no qué es
• Use palabras de acción: comience con verbos como “Control”, “Integrar”, “Habilitar”

Buenos ejemplos:

• “Dispositivo de control de linterna y antorcha con simple interruptor de encendido/apagado”
• “Integre el chat en vivo de Crisp y la atención al cliente en su aplicación”
• “Habilite la autenticación segura usando Face ID y Touch ID”

Malos ejemplos:

• “Un complemento para flash”
• “Este es un complemento Crisp”
• “Complemento biométrico”

Redacción de documentación1. Comience con la instalación: comience siempre con pasos de instalación claros

2. Proporcionar configuración: incluya requisitos de configuración específicos de la plataforma
3. Mostrar ejemplos de uso: proporcione ejemplos de código de trabajo
4. Incluir referencia API: documentar todos los métodos y parámetros
5. Agregar ejemplos completos: mostrar patrones de uso en el mundo real
6. Enumere las mejores prácticas: comparta sugerencias para un uso óptimo
7. Diferencias en la plataforma de documentos: Aclare el comportamiento de iOS frente a Android
8. Agregar solución de problemas: solucione problemas comunes

Ejemplos de código

• Utilice TypeScript para todos los ejemplos de código
• Incluir importaciones en la parte superior.
• Agregar comentarios que expliquen los pasos clave.
• Mostrar manejo de errores
• Demostrar el uso tanto básico como avanzado.

Lista de verificación

Utilice esta lista de verificación cuando agregue un nuevo complemento:

• [] Complemento agregado a /src/config/plugins.ts
• [] Icono apropiado seleccionado de Heroicons
• [] Se agregó complemento a /src/content/docs/docs/plugins/index.mdx en la categoría correcta
• [] Se agregó una entrada en la barra lateral en /astro.config.mjs
• [] Directorio de documentación del complemento creado
• [] Se creó la página de descripción general index.mdx
• [] Se creó la guía getting-started.mdx
• [] Tutorial creado en /src/content/plugins-tutorials/en/
• [] Instrucciones de instalación incluidas
• [] Configuración documentada iOS
• [] Configuración documentada Android
• [] Ejemplos de uso proporcionados
• [] Se agregó la referencia API
• [] Incluye ejemplo de trabajo completo
• [] Mejores prácticas enumeradas
• [] Se agregaron notas específicas de la plataforma.
• [] Probado que todos los enlaces funcionan correctamente

Referencia de icono

Iconos comunes utilizados para complementos (de astro-heroicons/mini/):

Icono	Caso de uso
BoltIcon	Flash, potencia, energía
CameraIcon	Cámara, fotografía, vídeo
ChatBubbleLeftIcon	Chat, mensajería, comunicación
FingerPrintIcon	Biométrica, seguridad, autenticación
MapPinIcon	Ubicación, geolocalización, mapas
SpeakerWaveIcon	Audio, sonido, música
VideoCameraIcon	Vídeo, grabación, streaming
CreditCardIcon	Pagos, compras
PlayCircleIcon	Reproductores multimedia, reproductores de vídeo
SignalIcon	Conectividad, red, baliza
RadioIcon	Baliza de radiodifusión inalámbrica
ChatBubbleOvalLeftIcon	Redes sociales, WeChat

Actualización de complementos existentes

Al actualizar un complemento existente:

1. Actualizar números de versión en la documentación
2. Agregue guías de migración si existen cambios importantes
3. Actualizar referencia API con nuevos métodos
4. Agregue nuevos ejemplos para nuevas funciones
5. Actualizar los requisitos de la plataforma si se modifica
6. Revisar las mejores prácticas según las nuevas funciones
7. Mantenga el tutorial actualizado con la última versión API

Soporte en varios idiomas

El sitio web admite varios idiomas. Después de crear la documentación en inglés:

1. Ejecute el script de traducción:

   bun run plugins:translate_all

2. Revisar las traducciones generadas en:

   • /src/content/plugins-tutorials/de/ (alemán)
   • /src/content/plugins-tutorials/es/ (español)
   • /src/content/plugins-tutorials/fr/ (francés)
   • /src/content/plugins-tutorials/it/ (italiano)
   • /src/content/plugins-tutorials/ja/ (japonés)
   • /src/content/plugins-tutorials/ko/ (coreano)
   • /src/content/plugins-tutorials/id/ (indonesio)

Probando tus cambios

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

1. Construya el sitio localmente:

   npm run build
   ```2. **Compruebe si hay errores**:
   - Verificar que todos los enlaces funcionen.
   - Asegúrese de que las imágenes se carguen correctamente
   - Confirmar que los ejemplos de códigos son válidos
   - La navegación de prueba funciona.

2. Vista previa del sitio:

   npm run dev

3. Verifica que aparezca tu complemento:

   • Verifique la página de listado de complementos
   • Verificar la navegación de la barra lateral
   • Pruebe todas las páginas de documentación.
   • Confirmar que la página del tutorial funciona.

Errores comunes

Precaución

Evite estos errores comunes:

1. Olvidar sincronizar: ejecute siempre npx cap sync en los ejemplos
2. Nombres inconsistentes: use el mismo nombre de complemento en todas partes
3. Falta configuración de plataforma: documente la configuración de iOS y Android
4. Enlaces rotos: utilice enlaces relativos y verifique que funcionen
5. Sin manejo de errores: muestra siempre try-catch en los ejemplos
6. Importaciones faltantes: incluya todas las importaciones necesarias en los ejemplos
7. Descripciones poco claras: Sea específico sobre lo que hace el complemento

Obtener ayuda

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

• Discord: Únete a nuestra comunidad de Discord
• GitHub: abrir una incidencia en el repositorio del sitio web
• Correo electrónico: póngase en contacto con el equipo en support@capgo.app

Ejemplos

Como referencia, consulte estos complementos bien documentados:

• Actualizador: /src/content/docs/docs/plugins/updater/ (complemento complejo con varias páginas)
• Flash: /src/content/docs/docs/plugins/flash/ (complemento simple, buen ejemplo inicial)
• Inicio de sesión social: /src/content/docs/docs/plugins/social-login/ (complemento con subpáginas)

Resumen

Agregar un complemento a la documentación Capgo implica:

1. Agregar metadatos a la configuración maestra
2. Agregar el complemento a la página de índice categorizada
3. Configurar la navegación de la barra lateral
4. Creación de páginas de documentación completas.
5. Escribir un tutorial detallado
6. Probar todos los cambios localmente

Si sigue esta guía, se asegurará de que los complementos estén documentados de forma coherente y sean fácilmente detectables por los usuarios.