시작하기
이 가이드에서는 Blockstudio을 설정하고 첫 사용자 지정 블록을 만드는 방법을 안내합니다.
설치
Composer을 통한 설치(권장)
composer require blockstudio/blockstudio
Blockstudio은 composer/installers을 통해 플러그인으로 설치하거나 테마에 직접 포함할 수 있습니다. 모든 설치 방법은 Composer문서를 참조하세요.
Composer 설치본은 Composer을 통해 업데이트됩니다. 기본 제공 GitHub 업데이트 프로그램은 자동으로 비활성화됩니다.
수동 설치
zip 파일을 WordPress 플러그인 디렉터리에 업로드한 다음 플러그인을 활성화하세요. 수동 설치본은 기본 제공 GitHub 업데이트 프로그램을 통해 WordPress 대시보드에서 자동 업데이트 알림을 받습니다.
두 설치 방법 모두 Markdown, YAML 및 업데이터 라이브러리와 해당 종속 항목의 비공개 사본을 번들로 포함합니다. 다른 플러그인이나 테마에서 제공하는 버전을 사용하거나 대체하지 않습니다. 애플리케이션에서 해당 라이브러리 중 하나를 직접 사용하는 경우 자체 Composer 종속 항목을 설치하세요. Blockstudio에 번들로 포함된 사본은 내부용이며 공개 PHP API가 아닙니다.
인증된 업데이트 확인
수동 설치는 기본적으로 GitHub를 익명으로 확인합니다. 하나의 아웃바운드 IP를 공유하는 사이트가 여러 개면 GitHub의 익명 API 허용량이 소진되어 업데이트 확인 시 HTTP 403 응답을 받을 수 있습니다. WordPress가 로드되기 전에 7.7.4에서 wp-config.php에 GitHub 개인 액세스 토큰을 설정하세요:
define('BLOCKSTUDIO_GITHUB_TOKEN', 'your-github-token');
토큰에는 공개 저장소 정보에 대한 액세스 권한만 있으면 됩니다. 쓰기 권한은 부여하지 마세요. 토큰은 서버 측 설정에 보관하고 버전 관리, blockstudio.json, 블록 속성 및 프런트엔드 코드에는 포함하지 마세요. 업데이터는 인증 확인 및 릴리스 다운로드를 위해 토큰을 번들에 포함된 GitHub 클라이언트에 전달합니다. 관련 없는 저장소와 다른 다운로드 호스트로 전송되는 요청에는 토큰이 포함되지 않습니다.
환경에서 관리하는 비밀 값을 사용하려면 MU 플러그인에서 토큰을 제공하거나 덮어쓸 수 있습니다:
<?php
add_filter('blockstudio/updater/token', function ($token) {
return getenv('BLOCKSTUDIO_GITHUB_TOKEN') ?: $token;
});
이 필터는 테마가 로드되기 전에 Blockstudio가 업데이터를 초기화할 때 실행됩니다. functions.php 대신 MU 플러그인에 등록하세요. 빈 문자열을 반환하면 상수가 정의되어 있어도 인증이 비활성화됩니다. 비어 있거나 문자열이 아닌 값은 익명 확인을 유지합니다. 토큰은 선택 사항이며 토큰이 없어도 기존 업데이트 동작은 그대로 유지됩니다. Composer 설치는 계속 업데이트에 Composer를 사용하며 이 업데이터를 초기화하지 않습니다.
첫 블록 만들기
1. 블록 디렉터리 만들기
테마에 새 디렉터리를 만드세요.
my-theme/
blockstudio/
my-first-block/
block.json
index.php
2. 블록 스키마 정의하기
블록 설정을 담은 block.json을 만드세요.
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/my-first-block",
"title": "My First Block",
"category": "common",
"icon": "star-filled",
"blockstudio": {
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Hello World"
},
{
"id": "content",
"type": "textarea",
"label": "Content"
}
]
}
}
3. 템플릿 만들기
렌더링을 위한 index.php을 만드세요.
<div class="my-first-block">
<h2><?php echo $a['heading']; ?></h2>
<p><?php echo $a['content']; ?></p>
</div>
Twig 템플릿 사용하기
Blockstudio은 Twig 템플릿을 기본 지원합니다. 대신 index.twig을 사용하면 됩니다.
<div class="my-first-block">
<h2>{{ a.heading }}</h2>
<p>{{ a.content }}</p>
</div>
스타일 추가하기
같은 폴더에 style.css 파일을 만드세요.
.my-first-block {
padding: 2rem;
background: #f5f5f5;
}
블록을 사용할 때 Blockstudio이 이 스타일시트를 자동으로 추가합니다.
번역
Blockstudio의 편집기 컨트롤과 관리자 개요는 JavaScript 번역을 WordPress을 통해 blockstudio 텍스트 도메인에 불러옵니다. 해당 언어 팩을 설치하거나 번역 도구로 스크립트 번역 JSON 파일을 wp-content/languages/plugins/에서 생성하세요. 사용 가능한 번역이 없는 문자열은 영어로 표시됩니다. 이는 Blockstudio 자체 인터페이스를 번역하며, 블록에서 정의하는 콘텐츠나 필드 레이블은 번역하지 않습니다.
다음 단계
이제 WordPress 편집기에서 블록을 사용할 수 있습니다. 문서를 계속 살펴보며 다음 내용을 알아보세요.
- 필드 유형 – 사용 가능한 모든 필드 유형
- 구성 요소 – InnerBlocks, RichText 등
- Tailwind 통합 – Tailwind CSS 사용하기
- 후크 – 필터와 액션으로 기능 확장하기
단일 블록에서 완전한 라이브러리로 확장하세요. 디자인 토큰, 섹션 패턴, 반복 필드, 이미지, 페이지 구성을 다룹니다.