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

このガイドでは、新しいCapacitorプラグインをCapgo Webサイトに追加する方法、または既存のプラグインドキュメントを更新する方法について説明します。これは、ドキュメントの保守を支援する貢献者、メンテナー、AIエージェントに役立ちます。

概要

新しいプラグインをCapgoエコシステムに追加する場合、プラグインがすべての関連する場所に正しく表示されるように、Webサイト全体のいくつかのファイルと場所を更新する必要があります:

プラグインリスト設定 - マスターリストにプラグインメタデータを追加
プラグインインデックスページ - カテゴリ別プラグインリストページにプラグインを追加
サイドバーナビゲーション - ドキュメントサイドバーにプラグインを追加
プラグインドキュメント - 概要とはじめにページを作成
プラグインチュートリアル - 包括的なチュートリアルを作成

ファイルの場所

更新する主要ファイル

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

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

プラグインをマスターリストに追加

/src/config/plugins.tsを開き、actions配列にプラグインを追加します:

// まず、適切なHeroiconをインポート
import YourIconName from 'astro-heroicons/mini/IconName.astro'

// 次にactionsアレイに追加
{
  name: '@capgo/your-plugin-name',
  author: 'github.com/Cap-go',
  description: 'プラグインが何をするかの簡単な説明',
  href: 'https://github.com/Cap-go/your-plugin-name/',
  title: '表示名',
  icon: YourIconName,
}

利用可能なアイコン: /node_modules/astro-heroicons/mini/で利用可能なアイコンを確認してください。

プラグインをインデックスページに追加
Section titled “プラグインをインデックスページに追加”

/src/content/docs/docs/plugins/index.mdxを開き、適切なカテゴリの下にプラグインを追加します:
```
<LinkCard
  title="Your Plugin Name"
  description="プラグインが何をするかの簡単な説明"
  href="/docs/plugins/your-plugin-name/"
/>
```
カテゴリ:
- ⭐ 注目のプラグイン
- 📱 デバイス＆システムプラグイン
- 🎥 メディア＆カメラプラグイン
- 🛠️ ユーティリティプラグイン
- 🤖 AI＆高度なメディア
- 📍 位置情報＆バックグラウンドサービス
- 📞 通信＆分析
- 🔐 セキュリティ＆システム
- 📊 Android固有機能
- 📥 ダウンロード＆ナビゲーション
サイドバーナビゲーションに追加
Section titled “サイドバーナビゲーションに追加”

/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,
}
```
プラグインはサイドバーでアルファベット順にリストされます。
プラグインドキュメントディレクトリを作成
Section titled “プラグインドキュメントディレクトリを作成”

プラグインドキュメント用の新しいディレクトリを作成します:
Terminal window
```
mkdir -p /src/content/docs/docs/plugins/your-plugin-name/
```

プラグイン概要ページを作成

/src/content/docs/docs/plugins/your-plugin-name/index.mdxを作成:

---
title: "@capgo/your-plugin-name"
description: プラグインの目的の簡単な説明
tableOfContents: false
next: false
prev: false
sidebar:
  order: 1
  label: "Introduction"
hero:
  tagline: プラグインが何をするかを説明する詳細なタグライン
  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">
    最初の主要機能の説明
  </Card>
  <Card title="Feature 2" icon="rocket">
    2番目の主要機能の説明
  </Card>
  <Card title="Cross-platform" icon="puzzle">
    iOSとAndroidの両方で動作 📱
  </Card>
  <Card title="Comprehensive Documentation" icon="open-book">
    [Documentation](/docs/plugins/your-plugin-name/getting-started/)を確認してプラグインをマスターしてください。
  </Card>
</CardGrid>

はじめにガイドを作成

/src/content/docs/docs/plugins/your-plugin-name/getting-started.mdxを作成:

---
title: Getting Started
description: Capacitorアプリでプラグインをインストールして使用する方法を学びます。
sidebar:
  order: 2
---

import { Steps } from '@astrojs/starlight/components';
import { PackageManagers } from 'starlight-package-managers'

<Steps>
1. **パッケージをインストール**
   <PackageManagers pkg="@capgo/your-plugin-name" pkgManagers={['npm', 'pnpm', 'yarn', 'bun']} />

2. **ネイティブプロジェクトと同期**
   <PackageManagers type="exec" pkg="cap" args="sync" pkgManagers={['npm', 'pnpm', 'yarn', 'bun']} />
</Steps>

## 設定

### iOS設定
[iOS固有のセットアップ手順]

### Android設定
[Android固有のセットアップ手順]

## 使用方法

[基本的な使用例]

## APIリファレンス

[詳細なAPIドキュメント]

## 完全な例

[完全な動作例]

## ベストプラクティス

[推奨される実践方法とヒント]

## プラットフォームノート

[プラットフォーム固有のノートと制限事項]

チュートリアルファイルを作成

/src/content/plugins-tutorials/en/your-plugin-name.mdを作成:

---
locale: en
---
# Using @capgo/your-plugin-name Package

The `@capgo/your-plugin-name` package [簡単な説明]。このチュートリアルでは、Ionic Capacitorアプリでこのパッケージのインストール、設定、使用方法を案内します。

## インストール

[インストール手順]

## 設定

[iOSとAndroidの設定手順]

## API使用

[詳細なAPI使用例]

## 完全な例

[完全な動作例]

## ベストプラクティス

[ヒントとベストプラクティス]

## トラブルシューティング

[一般的な問題と解決策]

## 結論

[概要と追加リソースへのリンク]

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

必須ファイル

src/content/docs/docs/plugins/your-plugin-name/
├── index.mdx           # ヒーローと機能カードのある概要ページ
└── getting-started.mdx # インストールと使用ガイド

src/content/plugins/en/
└── your-plugin-name.md # 包括的なチュートリアル

オプションファイル

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

src/content/docs/docs/plugins/your-plugin-name/
├── index.mdx
├── getting-started.mdx
├── api-reference.mdx   # 詳細なAPIドキュメント
├── examples.mdx        # 追加の例
├── troubleshooting.mdx # トラブルシューティングガイド
└── migrations.mdx      # 移行ガイド

コンテンツガイドライン

プラグイン説明の作成

簡潔に: 説明は100文字以下に保つ
具体的に: プラグインが何であるかではなく、何をするかを説明
動作語を使用: 「Control」、「Integrate」、「Enable」などの動詞で始める

良い例:

「デバイスのフラッシュライトとトーチをシンプルなオン/オフトグルで制御」
「アプリにCrispライブチャットとカスタマーサポートを統合」
「Face IDとTouch IDを使用した安全な認証を有効化」

悪い例:

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

ドキュメントの作成

インストールから開始: 常に明確なインストール手順から始める
設定を提供: プラットフォーム固有のセットアップ要件を含める
使用例を表示: 動作するコード例を提供
APIリファレンスを含める: すべてのメソッドとパラメータをドキュメント化
完全な例を追加: 実世界の使用パターンを表示
ベストプラクティスをリスト: 最適な使用のためのヒントを共有
プラットフォームの違いをドキュメント化: iOSとAndroidの動作を明確化
トラブルシューティングを追加: 一般的な問題に対処

コード例

すべてのコード例にTypeScriptを使用
上部にインポートを含める
主要な手順を説明するコメントを追加
エラー処理を表示
基本的な使用法と高度な使用法の両方を示す

チェックリスト

新しいプラグインを追加する際は、このチェックリストを使用してください:

アイコンリファレンス

プラグインに使用される一般的なアイコン（astro-heroicons/mini/から）:

アイコン	使用例
`BoltIcon`	フラッシュ、電源、エネルギー
`CameraIcon`	カメラ、写真、ビデオ
`ChatBubbleLeftIcon`	チャット、メッセージング、通信
`FingerPrintIcon`	バイオメトリック、セキュリティ、認証
`MapPinIcon`	位置情報、ジオロケーション、地図
`SpeakerWaveIcon`	オーディオ、サウンド、音楽
`VideoCameraIcon`	ビデオ、録画、ストリーミング
`CreditCardIcon`	支払い、購入
`PlayCircleIcon`	メディアプレーヤー、ビデオプレーヤー
`SignalIcon`	接続性、ネットワーク、ビーコン
`RadioIcon`	ビーコン、ブロードキャスト、ワイヤレス
`ChatBubbleOvalLeftIcon`	ソーシャルメディア、WeChat

既存のプラグインの更新

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

バージョン番号を更新 ドキュメント内
移行ガイドを追加 破壊的変更がある場合
新しいメソッドでAPIリファレンスを更新
新機能の新しい例を追加
プラットフォーム要件を更新 変更された場合
新機能に基づいてベストプラクティスを改訂
最新のAPIでチュートリアルを最新に保つ

多言語サポート

英語ドキュメントを作成した後:

翻訳スクリプトを実行:
Terminal window
```
bun run plugins:translate_all
```
生成された翻訳を確認:
- /src/content/plugins-tutorials/de/（ドイツ語）
- /src/content/plugins-tutorials/es/（スペイン語）
- /src/content/plugins-tutorials/fr/（フランス語）
- /src/content/plugins-tutorials/it/（イタリア語）
- /src/content/plugins-tutorials/ja/（日本語）
- /src/content/plugins-tutorials/ko/（韓国語）
- /src/content/plugins-tutorials/id/（インドネシア語）

変更のテスト

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

サイトをローカルでビルド:
Terminal window
```
npm run build
```
エラーを確認:
- すべてのリンクが機能することを確認
- 画像が正しくロードされることを確認
- コード例が有効であることを確認
- ナビゲーションが機能することをテスト
サイトをプレビュー:
Terminal window
```
npm run dev
```
プラグインが表示されることを確認:
- プラグインリストページを確認
- サイドバーナビゲーションを確認
- すべてのドキュメントページをテスト
- チュートリアルページが機能することを確認

一般的な落とし穴

ヘルプを得る

プラグインドキュメントの追加または更新に助けが必要な場合:

Discord: Discordコミュニティに参加
GitHub: Webサイトリポジトリで問題を開く
メール: support@capgo.appでチームに連絡

例

参考のために、これらのよくドキュメント化されたプラグインを確認してください:

Updater: /src/content/docs/docs/plugins/updater/（複数ページのある複雑なプラグイン）
Flash: /src/content/docs/docs/plugins/flash/（シンプルなプラグイン、良いスターター例）
Social Login: /src/content/docs/docs/plugins/social-login/（サブページのあるプラグイン）

まとめ

Capgoドキュメントにプラグインを追加するには:

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

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