Skip to content

Commit 4f2802e

Browse files
AdammatthiesenAdammatthiesen
authored
Merge branch 'main' into studiocms-beta.16
2 parents 6745542 + 30a473d commit 4f2802e

File tree

2 files changed

+299
-1
lines changed

2 files changed

+299
-1
lines changed

‎src/content/docs/ko/plugins/extended.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
i18nReady: true
3-
title: 플러그인을 유용하게 만들기
3+
title: 유용한 플러그인 만들기
44
description: StudioCMS 플러그인과 그 작동 방식에 대해 알아보세요.
55
sidebar:
66
order: 2

‎src/content/docs/ko/plugins/index.mdx‎

Lines changed: 298 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,298 @@
1+
---
2+
i18nReady: true
3+
title: 기본 사항
4+
description: StudioCMS 플러그인과 작동 방식에 대해 알아보세요.
5+
sidebar:
6+
order: 1
7+
---
8+
9+
import ReadMore from '~/components/ReadMore.astro'
10+
11+
# 소개
12+
13+
StudioCMS 플러그인은 StudioCMS의 기능을 확장할 수 있는 강력한 도구입니다. 이는 StudioCMS 프로젝트에 새로운 기능을 추가하는 간단하고 유연한 방법을 제공합니다. 다음은 StudioCMS 플러그인과 작동 방식에 대한 분석입니다.
14+
15+
## 플러그인이란 무엇인가요?
16+
17+
StudioCMS 플러그인은 Astro 통합과 유사하지만, 함수 객체에 추가적인 정보가 첨부되어 있습니다. 이 정보는 StudioCMS가 플러그인을 어떻게 로드하고 사용해야 하는지 결정하는 데 사용됩니다. StudioCMS 플러그인은 새로운 기능을 추가하거나 기존 기능을 수정하여 StudioCMS의 기능을 확장하는 데 사용됩니다.
18+
19+
### StudioCMS 플러그인 타입
20+
21+
```ts twoslash
22+
import { APIRoute, AstroIntegration } from "astro"
23+
import type { HeroIconName } from '@studiocms/ui/components/Icon/iconType.js';
24+
import type { SanitizeOptions } from 'ultrahtml/transformers/sanitize';
25+
import type { SettingsField } from 'studiocms/schemas';
26+
// ---cut---
27+
type StudioCMSPlugin = {
28+
/**
29+
* package.json에 정의된 플러그인의 식별자입니다.
30+
*/
31+
identifier: string;
32+
33+
/**
34+
* StudioCMS 대시보드에 표시되는 플러그인의 레이블입니다.
35+
*/
36+
name: string;
37+
38+
/**
39+
* 플러그인이 작동하는 데 필요한 StudioCMS의 최소 버전입니다.
40+
*/
41+
studiocmsMinimumVersion: string;
42+
43+
/**
44+
* 플러그인이 제공하는 Astro 통합입니다.
45+
*/
46+
integration?: AstroIntegration | AstroIntegration[] | undefined;
47+
48+
/**
49+
* true일 경우, 플러그인은 사이트맵 생성을 활성화합니다.
50+
*/
51+
triggerSitemap?: boolean;
52+
53+
/**
54+
* 플러그인이 사이트맵 엔드포인트를 추가할 수 있도록 허용합니다.
55+
*/
56+
sitemaps?: Array<{
57+
58+
/**
59+
* 플러그인의 이름입니다.
60+
*/
61+
pluginName: string;
62+
63+
/**
64+
* 사이트맵 XML 엔드포인트 파일의 경로입니다.
65+
*/
66+
sitemapXMLEndpointPath: string | URL;
67+
}> | undefined;
68+
69+
/**
70+
* 플러그인이 사용자 정의 대시보드 그리드 항목을 추가할 수 있도록 허용합니다.
71+
*/
72+
dashboardGridItems?: Array<{
73+
74+
/**
75+
* 그리드 항목의 이름입니다.
76+
*/
77+
name: string;
78+
79+
/**
80+
* 그리드 항목의 너비입니다.
81+
*/
82+
span: 1 | 2 | 3;
83+
84+
/**
85+
* 그리드 항목의 카드 변형입니다.
86+
*/
87+
variant: 'default' | 'filled';
88+
89+
/**
90+
* 그리드 항목을 보기 위해 필요한 권한입니다.
91+
*/
92+
requiresPermission?: "owner" | "admin" | "editor" | "visitor";
93+
94+
/**
95+
* 그리드 항목의 헤더 정보입니다.
96+
*/
97+
header?: {
98+
99+
/**
100+
* 그리드 항목의 제목입니다.
101+
*/
102+
title: string;
103+
104+
/**
105+
* 그리드 항목의 아이콘입니다.
106+
*/
107+
icon?: HeroIconName;
108+
};
109+
110+
/**
111+
* 그리드 항목의 본문 정보입니다.
112+
*/
113+
body?: {
114+
115+
/**
116+
* 그리드 항목의 HTML 콘텐츠입니다.
117+
*/
118+
html: string;
119+
120+
/**
121+
* 그리드 항목에 표시되는 컴포넌트입니다.
122+
*/
123+
components?: Record<string, string>;
124+
125+
/**
126+
* HTML 콘텐츠를 위한 정리 옵션입니다.
127+
*/
128+
sanitizeOpts?: SanitizeOptions;
129+
};
130+
}> | undefined;
131+
132+
/**
133+
* 이 속성이 존재하면, 플러그인은 자체 설정 페이지를 갖게 됩니다.
134+
*/
135+
settingsPage: {
136+
137+
/**
138+
* 명세에 따른 필드입니다.
139+
*/
140+
fields: SettingsField[];
141+
142+
/**
143+
* 설정에 대한 엔드포인트입니다.
144+
*
145+
* 저장 페이지가 저장될 때 실행되는 `onSave`라는 이름의 APIRoute를 내보내야 합니다.
146+
*/
147+
endpoint: string,
148+
} | undefined;
149+
150+
/**
151+
* `@studiocms/blog` 플러그인 및 기타 플러그인과 함께 프론트엔드에 링크를 표시하는 데 사용되는 탐색 링크입니다.
152+
*/
153+
frontendNavigationLinks: Array<{
154+
label: string;
155+
href: string;
156+
}>;
157+
158+
/**
159+
* 페이지 타입 정의입니다. 이 속성이 존재하면, 플러그인은 페이지 생성 프로세스를 수정할 수 있기를 원합니다.
160+
*/
161+
pageTypes: Array<{
162+
163+
/**
164+
* 선택 입력창에 표시되는 레이블입니다.
165+
*/
166+
label: string;
167+
168+
/**
169+
* 데이터베이스에 저장되는 식별자입니다.
170+
* @example
171+
* // 플러그인당 단일 페이지 타입입니다.
172+
* 'studiocms'
173+
* '@studiocms/blog'
174+
* // 플러그인당 여러 페이지 타입입니다. (충돌을 피하기 위해 각 타입에 고유한 식별자를 사용하세요.)
175+
* '@mystudiocms/plugin:pageType1'
176+
* '@mystudiocms/plugin:pageType2'
177+
* '@mystudiocms/plugin:pageType3'
178+
* '@mystudiocms/plugin:pageType4'
179+
*/
180+
identifier: string;
181+
182+
/**
183+
* 이 타입이 선택되었을 때 "Page Content" 헤더 아래에 표시되는 설명입니다.
184+
*/
185+
description: string;
186+
187+
/**
188+
* 페이지 콘텐츠에 실제로 표시되는 컴포넌트의 경로입니다.
189+
*
190+
* 컴포넌트는 현재 콘텐츠를 표시하기 위한 문자열인 `content` prop을 가져야 합니다.
191+
*
192+
* **참고:** 현재는 콘텐츠 출력을 위해 `page-content`라는 양식 id를 사용해야 합니다. 편집기는 또한 양식 제출을 처리할 수 있어야 합니다.
193+
*
194+
* **참고:** HTML 또는 Markdown 콘텐츠로 작업하는 경우 대체 값으로 `studiocms/markdown` 또는 `studiocms/html`을 사용할 수 있습니다!
195+
*
196+
* @example
197+
* ```ts
198+
* import { createResolver } from 'astro-integration-kit';
199+
* const { resolve } = createResolver(import.meta.url)
200+
*
201+
* {
202+
* pageContentComponent: resolve('./components/MyContentEditor.astro'),
203+
* }
204+
* ```
205+
*/
206+
pageContentComponent: 'studiocms/markdown' | 'studiocms/html' | string;
207+
208+
/**
209+
* 페이지 렌더러에 실제로 표시되는 컴포넌트의 경로입니다.
210+
*
211+
* **참고:** HTML 또는 Markdown 콘텐츠로 작업하는 경우 대체 값으로 `studiocms/markdown` 또는 `studiocms/html`을 사용할 수 있습니다!
212+
*/
213+
rendererComponent: 'studiocms/markdown' | 'studiocms/html' | string;
214+
215+
/**
216+
* 명세에 따른 필드입니다.
217+
*/
218+
fields: SettingsField[];
219+
220+
/**
221+
* 페이지 타입에 대한 API 엔드포인트 파일입니다.
222+
*
223+
* API 엔드포인트는 이 타입의 페이지를 생성, 편집 및 삭제하는 데 사용됩니다.
224+
* 엔드포인트는 Astro APIRoute에서 전체 Astro APIContext를 제공받습니다.
225+
*
226+
* 파일은 다음 중 적어도 하나를 내보내야 합니다.
227+
* - `onCreate`
228+
* - `onEdit`
229+
* - `onDelete`
230+
*
231+
* @example
232+
* ```ts
233+
* // my-plugin.ts
234+
* import { createResolver } from 'astro-integration-kit';
235+
* const { resolve } = createResolver(import.meta.url)
236+
*
237+
* {
238+
* apiEndpoint: resolve('./api/pageTypeApi.ts'),
239+
* }
240+
*
241+
* // api/pageTypeApi.ts
242+
* import { APIRoute } from 'astro';
243+
*
244+
* export const onCreate: APIRoute = async (ctx) => {
245+
* // 여기에 사용자 정의 로직을 작성합니다.
246+
* return new Response();
247+
* }
248+
* ```
249+
*/
250+
apiEndpoint: string;
251+
}> | undefined;
252+
};
253+
```
254+
255+
### 플러그인 정의
256+
257+
StudioCMS 플러그인을 정의하려면 `StudioCMSPlugin` 타입에 부합하는 객체를 생성해야 합니다. 이 객체는 다음과 유사한 형태를 가져야 하며, 다음 속성들은 필수 사항입니다.
258+
259+
- `identifier`: package.json 파일에 정의된 플러그인의 식별자입니다.
260+
- `name`: StudioCMS 대시보드에 표시되는 플러그인의 레이블입니다.
261+
- `studiocmsMinimumVersion`: 플러그인이 작동하는 데 필요한 StudioCMS의 최소 버전입니다.
262+
263+
다음은 필요한 모든 속성을 포함하고 사용자 정의 로직을 수행하는 Astro 통합을 제공하는 StudioCMS 플러그인 정의의 예시입니다.
264+
265+
```ts twoslash title="my-plugin.ts"
266+
import { definePlugin } from 'studiocms/plugins';
267+
import { AstroIntegration } from 'astro';
268+
269+
// 플러그인 및 통합에 대한 옵션을 정의합니다.
270+
interface Options {
271+
foo: string;
272+
}
273+
274+
// Astro 통합을 정의합니다.
275+
const myIntegration = (options: Options): AstroIntegration => ({
276+
name: 'my-astro-integration',
277+
hooks: {
278+
"astro:config:setup": () => {
279+
console.log('Hello from my Astro Integration!');
280+
}
281+
}
282+
});
283+
284+
// StudioCMS 플러그인을 정의합니다.
285+
export const myPlugin = (options: Options) => definePlugin({
286+
identifier: 'my-plugin',
287+
name: 'My Plugin',
288+
studiocmsMinimumVersion: '0.1.0-beta.8',
289+
integration: myIntegration(options), // 선택 사항이지만, 권장 사항입니다.
290+
});
291+
```
292+
293+
이 예시에서는 StudioCMS 버전 `0.1.0-beta.8` 이상을 요구하는 `My Plugin`이라는 StudioCMS 플러그인을 정의합니다. 이 플러그인은 `astro:config:setup` 훅이 호출될 때 콘솔에 메시지를 기록하는 Astro 통합도 제공합니다.
294+
295+
<ReadMore>플러그인 구축에 대한 더 자세한 정보는 [유용한 플러그인 만들기][extended-plugins] 가이드를 확인하세요.</ReadMore>
296+
297+
{/* Links */}
298+
[extended-plugins]: /ko/plugins/extended/

0 commit comments

Comments
 (0)