플러그인 추가 또는 업데이트

이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.

이 가이드는 Capgo 웹사이트에 새 Capacitor 플러그인을 추가하거나 기존 플러그인 문서를 업데이트하는 방법을 설명합니다. 기여자, 유지보수자, 문서 유지보수를 돕는 AI 에이전트에게 유용합니다.

개요

Capgo 생태계에 새 플러그인을 추가할 때는 플러그인이 모든 관련 위치에 올바르게 표시되도록 웹사이트 전반의 여러 파일과 위치를 업데이트해야 합니다.

플러그인 목록 설정 - 마스터 목록에 플러그인 메타데이터 추가
플러그인 인덱스 페이지 - 카테고리별 플러그인 목록 페이지에 플러그인 추가
사이드바 내비게이션 - 문서 사이드바에 플러그인 추가
플러그인 문서 - 개요 및 시작하기 페이지 작성
플러그인 튜토리얼 - 상세 튜토리얼 작성

파일 위치

업데이트가 필요한 주요 파일

파일	목적
`/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 배열에 추가하세요:

// 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/ 사용 가능한 아이콘을 확인하세요.

인덱스 페이지에 플러그인 추가
“인덱스 페이지에 플러그인 추가” 섹션

열기 /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 전용 기능
- 📥 다운로드 및 네비게이션
사이드바 네비게이션에 추가
“사이드바 네비게이션에 추가” 섹션

열기 /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,
}
```
사이드바의 플러그인은 알파벳 순으로 나열됩니다.
플러그인 문서 디렉토리 생성
“플러그인 문서 디렉토리 생성” 섹션

플러그인 문서용 새 디렉토리를 만드세요:
터미널 창
```
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: 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>

시작하기 가이드 생성

생성 /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]

튜토리얼 파일 생성하기

생성 /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”과 같은 동사로 시작하세요

좋은 예시:

“간단한 On/Off 토글로 기기의 플래시와 손전등을 제어합니다”
“Crisp 라이브 채팅과 고객 지원 기능을 앱에 통합하세요”
“Face ID 및 Touch ID를 사용한 안전한 인증을 지원합니다”

잘못된 예시:

“플래시용 플러그인”
“이것은 Crisp 플러그인입니다”
“생체 인식 플러그인”

문서 작성 가이드

설치 방법부터 시작하기: 항상 명확한 설치 단계를 먼저 제공하세요
설정 방법 제공: 플랫폼별 설정 요구사항 포함
사용 예시 보기: 작동 가능한 code 예시 제공
API 레퍼런스 포함: 모든 메서드 및 파라미터 문서화
전체 예시 추가: 실제 사용 패턴 제시
Best Practices 목록: 최적의 사용을 위한 팁 공유
플랫폼별 차이점 문서화: iOS와 Android 동작 차이 명시
Troubleshooting 추가: 일반적인 문제 해결하기

Code 예제

모든 code 예제에는 TypeScript를 사용하세요
상단에 import 문을 포함하세요
주요 단계를 설명하는 주석을 추가하세요
에러 핸들링을 보여주세요
기본 및 고급 사용법을 모두 보여주세요

체크리스트

새 플러그인을 추가할 때 다음 체크리스트를 확인하세요:

아이콘 참조

플러그인에 자주 사용하는 아이콘 (출처: astro-heroicons/mini/):

아이콘	사용 사례
`BoltIcon`	플래시, 전원, 에너지
`CameraIcon`	카메라, 사진, 비디오
`ChatBubbleLeftIcon`	채팅, 메시징, 통신
`FingerPrintIcon`	생체 인식, 보안, 인증
`MapPinIcon`	위치, 지오로케이션, 지도
`SpeakerWaveIcon`	오디오, 사운드, 음악
`VideoCameraIcon`	비디오, 녹화, 스트리밍
`CreditCardIcon`	결제, 구매
`PlayCircleIcon`	미디어 플레이어, 비디오 플레이어
`SignalIcon`	연결성, 네트워크, 비콘
`RadioIcon`	비콘, 브로드캐스트, 무선
`ChatBubbleOvalLeftIcon`	소셜 미디어, WeChat

기존 플러그인 업데이트하기

기존 플러그인을 업데이트할 때:

버전 번호 업데이트 문서 내
마이그레이션 가이드 추가 Breaking Change가 있는 경우
API 참조 업데이트 새 메서드 포함
새로운 예제 추가 새 기능에 대한
플랫폼 요구 사항 업데이트 변경 시
베스트 프랙티스 수정 새로운 기능 기반
튜토리얼 최신 상태 유지 최신 API 반영

언어별 경로

플러그인 문서는 영어로 작성 및 검토합니다. 로컬라이즈된 경로는 사이트 메타데이터를 통해 생성되며, translation Worker가 에지(edge)에서 번역을 수행합니다.

변경 사항 테스트

플러그인 문서를 추가하거나 업데이트한 후:

로컬에서 사이트 빌드:
터미널 창
```
bun run build
```
오류 확인:
- 모든 링크 작동 여부 확인
- 이미지가 제대로 로드되는지 확인
- code 예제가 유효한지 확인
- 네비게이션 작동 테스트
사이트 미리보기:
터미널 창
```
bun run dev
```
플러그인 노출 여부 확인:
- 플러그인 목록 페이지 확인
- 사이드바 네비게이션 확인
- 모든 문서 페이지 테스트
- 튜토리얼 페이지 작동 확인

흔히 발생하는 실수

도움 받기

플러그인 문서를 추가하거나 업데이트하는 데 도움이 필요하다면:

Discord에서: 다음 채널에 참여하세요: Discord 커뮤니티에
GitHub: 다음에서 이슈를 생성하세요: 웹사이트 저장소
이메일: 다음으로 팀에 문의하세요: support@capgo.app

예시

참고로, 문서화가 잘 된 다음 플러그인들을 확인해 보세요:

업데이터: /src/content/docs/docs/plugins/updater/ (여러 페이지로 구성된 복잡한 플러그인)
플래시: /src/content/docs/docs/plugins/flash/ (입문용으로 좋은 간단한 플러그인)
소셜 로그인: /src/content/docs/docs/plugins/social-login/ (하위 페이지가 포함된 플러그인)

요약

Capgo 문서에 플러그인을 추가하려면 다음 작업이 필요합니다:

마스터 설정에 메타데이터 추가
카테고리별 인덱스 페이지에 플러그인 추가
사이드바 네비게이션 설정
상세 문서 페이지 작성
상세 튜토리얼 작성
모든 변경 사항 로컬 테스트

이 가이드를 따르면 플러그인이 일관되게 문서화되어 사용자가 쉽게 찾을 수 있습니다.

플러그인 추가/업데이트에서 계속하기

사용 중이라면 플러그인 추가 또는 업데이트 네이티브 플러그인 작업을 계획하려면, 이를 다음 항목과 연결하세요: Capgo 플러그인 디렉토리 Capgo Plugin Directory의 제품 워크플로우에 맞춰, Capgo의 Capacitor 플러그인 Capgo의 Capacitor 플러그인 구현 상세 내용에 대해서는, Ionic Enterprise 플러그인 대안 Ionic Enterprise 플러그인 대안의 제품 워크플로우를 위해, Capgo Native Build 그리고 Capgo Native Builds의 제품 워크플로우를 위해, Capacitor 플러그인: 꼭 알아야 할 점 Capacitor 플러그인: 실무적인 맥락을 파악하기 위해 알아야 할 사항.