プラグインの追加または更新

This guide explains how to add new Capacitor plugins to the Capgo website or update existing plugin documentation. This is useful for contributors, maintainers, and AI agents helping to maintain the documentation.

概要

Capgo エコシステムに新しいプラグインを追加する場合、ウェブサイトのさまざまな場所に複数のファイルと場所を更新する必要があります。これにより、すべての関連する場所でプラグインが正しく表示されるようにします:

1. プラグインリストの設定 - マスター リストにプラグイン メタデータを追加する
2. プラグイン インデックス ページ - カテゴリー化されたプラグイン リスト ページにプラグインを追加する
3. サイド バー ナビゲーション - ドキュメントサイドバーにプラグインを追加
4. プラグインドキュメント - オーバービューとスタートガイドページを作成
5. プラグインチュートリアル - 広範なチュートリアルを作成

ファイルの場所

更新する必要がある主なファイル

ファイル	目的
/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/	英語のチュートリアルファイル

ステップバイステップのガイド

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/"
   />

   📱 デバイス＆システム プラグイン:

   • 🎥 メディア＆カメラ プラグイン
   • 📚 その他のカテゴリ
   • 🔍 検索
   • 🛠️ ユーティリティ プラグイン
   • 🤖 AI と高度なメディア
   • 📍 場所とバックグラウンド サービス
   • 📞 通信と分析
   • 🔐 セキュリティとシステム
   • 📊 Android固有の機能
   • 📥 ダウンロードとナビゲーション

3. サイド バー ナビゲーションに追加

   Open /astro.config.mjs __CAPGO_KEEP_0__とサイド バー 設定にプラグインを追加してください (約 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]

プラグインドキュメント構造

必要なファイル

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

任意のファイル

複雑なプラグインの場合、追加のドキュメントページを追加できます:

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文字以下で説明する
• 具体的に：プラグインが何をするかを説明する
• アクションワードを使用：動詞で始めるように「制御」、「統合」、「有効化」を使ってください。

良い例:

• 「簡単なオン/オフのスイッチでデバイスのフラッシュライトとトーチを制御する」
• 「アプリにライブチャットと顧客サポートを統合する」
• 「Face IDとTouch IDを使用した安全な認証を有効化する」

悪い例:

• 「フラッシュ用のプラグイン」
• 「このはCrispプラグイン」
• 「バイオメトリックプラグイン」

ドキュメントの書き方

1. インストールから始めるインストール手順を明確に示す
2. 設定を提供するプラットフォーム固有のセットアップ要件を含む
3. 実際の使用例を示す実行可能なcode例を提供する
4. APIリファレンスを含むすべてのメソッドとパラメータをドキュメントする
5. 完全な例を追加する実際の使用パターンを示す
6. ベストプラクティスをリストする最適な使用方法に関するアドバイスを共有する
7. プラットフォーム間の差異をドキュメントする: iOS と Android の動作を明確にする
8. トラブルシューティングを追加する: 一般的な問題を解決する

Code の例

• すべての code の例で TypeScript を使用する
• トップに import を含める
• 重要なステップの説明を含める
• エラー処理を示す
• 基本的な使用法と高度な使用法の両方を示す

チェックリスト

新プラグインを追加する際に使用するチェックリスト:

• プラグインを /src/config/plugins.ts
• Heroiconsから適切なアイコンを選択しました。
• プラグインを /src/content/docs/docs/plugins/index.mdx 正しいカテゴリの下に追加しました。
• サイドバーにエントリを追加しました。 /astro.config.mjs
• プラグインドキュメントディレクトリを作成しました。
• 概要ページを作成しました。 index.mdx ガイドを作成しました。
• チュートリアルを作成しました。 getting-started.mdx __CAPGO_KEEP_0__
• __CAPGO_KEEP_1__ /src/content/plugins-tutorials/en/
• インストール方法が含まれています
• iOSの設定がドキュメント化されています
• Androidの設定がドキュメント化されています
• 使用例が提供されています
• APIの参照が追加されました
• 完全な実行可能な例が含まれています
• ベストプラクティスがリストされています
• プラットフォーム固有の注釈が追加されました
• すべてのリンクが正しく機能することをテストしました

アイコン参照

プラグイン用に共通のアイコンが使用されています (から astro-heroicons/mini/):

アイコン	用途
BoltIcon	フラッシュ、電力、エネルギー
CameraIcon	カメラ、写真、ビデオ
ChatBubbleLeftIcon	チャット、メッセージング、コミュニケーション
FingerPrintIcon	バイオメトリクス、セキュリティ、認証
MapPinIcon	位置、地理位置、地図
SpeakerWaveIcon	オーディオ、サウンド、音楽
VideoCameraIcon	ビデオ、記録、ストリーミング
CreditCardIcon	決済、購入
PlayCircleIcon	メディアプレーヤー、ビデオプレーヤー
SignalIcon	接続性、ネットワーク、ビーコン
RadioIcon	ビーコン、ブロードキャスト、無線
ChatBubbleOvalLeftIcon	SNS、WeChat

既存のプラグインの更新

既存のプラグインを更新する場合:

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. syncを忘れることがある : 常に実行する bunx cap sync 例の場合
2. 命名規則の不一致例：同じプラグイン名を使用する
3. プラットフォームの設定が欠落している例：iOSとAndroidのセットアップを両方ドキュメントする
4. リンクが壊れている例：相対リンクを使用し、リンクが機能することを確認する
5. エラー処理が欠落している例：例で常にtry-catchを表示する
6. 必要なインポートが欠落している例：例で必要なインポートをすべて含める
7. 説明が曖昧である: プラグインの機能を詳しく説明してください。

ヘルプを求める

プラグインの追加または更新のドキュメントを追加または更新する必要がある場合のヘルプを求めます:

• Discord: 連絡先はこちら CapgoのDiscordコミュニティ
• GitHub: Capgoのウェブサイトのリポジトリにissueを提出してください。 Email
• : Capgoチームに連絡してください。Capgo 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. すべての変更をローカルでテストする

このガイドを遵守することで、プラグインはユーザーが容易に発見できるように、統一されたドキュメントで提供されます。

「プラグインを追加または更新する」から続けてください。

「プラグインを追加または更新する」を使用している場合 「プラグインを追加または更新する」 native プラグインの作業を計画するには、を接続する必要があります。 Capgo プラグイン ディレクトリ Capgo プラグイン ディレクトリ内での製品ワークフローについて Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, Ionic Enterprise プラグインの代替 Ionic Enterprise プラグインの代替の製品ワークフローについて Capgo ネイティブ ビルド Capgo ネイティブ ビルドの製品ワークフローについて、 Capacitor プラグイン: 重要な事項 Capacitor プラグインの実用的な背景について