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

このガイドでは、Capgo ウェブサイトに新しい Capacitor プラグインを追加する方法、または既存のプラグインドキュメントを更新する方法について説明します。これは、コントリビューター、メンテナー、およびドキュメントの保守を支援する AI エージェントにとって有用な情報です。

概要

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 array:

   // 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. サイドバーナビゲーションに追加

   開く /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]

プラグインドキュメントの構成

必須ファイル

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文字以内に収める
• 具体的に書く: プラグインが「何であるか」ではなく「何ができるか」を説明する
• 動詞を活用する: 「Control」「Integrate」「Enable」などの動詞から始める

良い例:

• 「簡単なオン/オフの切り替えで、デバイスのフラッシュライトやトーチを制御」
• 「Crispのライブチャットとカスタマーサポートをアプリに統合」
• 「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から適切なアイコンを選択
• Added plugin to /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	フラッシュ、電源、エネルギー
CameraIcon	カメラ、写真、ビデオ
ChatBubbleLeftIcon	チャット、メッセージング、通信
FingerPrintIcon	生体認証、セキュリティ、認証
MapPinIcon	位置情報、ジオロケーション、地図
SpeakerWaveIcon	オーディオ、サウンド、音楽
VideoCameraIcon	ビデオ、録画、ストリーミング
CreditCardIcon	決済、購入
PlayCircleIcon	メディアプレーヤー、ビデオプレーヤー
SignalIcon	接続性、ネットワーク、ビーコン
RadioIcon	ビーコン、ブロードキャスト、ワイヤレス
ChatBubbleOvalLeftIcon	ソーシャルメディア、WeChat

既存プラグインの更新

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

1. バージョン番号を更新する ドキュメント内の
2. 移行ガイドを追加する 破壊的変更がある場合
3. API のリファレンスを更新する 新しいメソッドで
4. 新しいサンプルを追加する 新機能向けの
5. プラットフォーム要件を更新する 変更がある場合
6. ベストプラクティスの見直し 新機能に基づいて
7. チュートリアルの最新化 最新の API を使用して

言語パス

プラグインのドキュメントは英語で作成・レビューしてください。ローカライズされたパスはサイトのメタデータによって生成され、translation Workerによってエッジで翻訳されます。

変更内容のテスト

プラグインのドキュメントを追加または更新した後：

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：コミュニティに参加する Discordコミュニティ
• GitHub：以下のリポジトリでIssueを作成する ウェブサイトのリポジトリ
• メールアドレス：チームへ連絡する support@capgo.app

例

参考までに、ドキュメントが充実している以下のプラグインをチェックしてください：

• アップデーター: /src/content/docs/docs/plugins/updater/ (複数ページ構成の複雑なプラグイン)
• Flash: /src/content/docs/docs/plugins/flash/ (シンプルなプラグイン。入門例として最適)
• ソーシャルログイン: /src/content/docs/docs/plugins/social-login/ (サブページがあるプラグイン)

まとめ

Capgo ドキュメントにプラグインを追加する手順：

1. マスター設定へのメタデータの追加
2. カテゴリ別インデックスページへのプラグイン追加
3. サイドバーナビゲーションの設定
4. 包括的なドキュメントページの作成
5. 詳細なチュートリアルを書く
6. すべての変更をローカルでテスト

このガイドに従えば、プラグインが一貫してドキュメント化され、ユーザーが簡単に見つけられるようになります。

Adding or Updating Plugins から続ける

使用している場合 プラグインの追加または更新 ネイティブプラグインの作業を計画するには、次と連携してください： Capgo プラグインディレクトリ Capgo プラグインディレクトリのプロダクトワークフローについては、 Capgo による Capacitor プラグイン Capgo による Capacitor プラグインの実装詳細については、 Ionic Enterprise プラグインの代替案 Ionic Enterprise Plugin Alternatives のプロダクトワークフロー向けに、 Capgo Native Build Capgo Native Builds のプロダクトワークフロー、および Capacitor プラグイン：知っておくべきこと Capacitor プラグインの実践的なコンテキスト：知っておくべきこと。