Dennis · 2026년 6월 21일
Blockstudio 7.4
Blockstudio 7.4는 파일 기반 프로젝트의 이식성을 높이는 데 초점을 맞춥니다. 7.2가 규모가 큰 프로젝트를 살펴보고 배포하기 쉽게 만들고 7.3이 그 위에 UI 계층을 더했다면, 7.4는 프로젝트와 페이지, 선별된 콘텐츠를 데이터베이스에서 버전 관리 파일로 더 많이 옮기는 데 집중합니다.
핵심 기능은 페이지 컬렉션입니다. 폴더를 Blockstudio에 지정하면 완전한 중첩 WordPress 페이지 구조를 생성할 수 있습니다. 소스로는 PHP, Twig, Blade, HTML, Markdown 또는 다른 로컬 소스의 페이지를 반환하는 신뢰할 수 있는 로더를 사용할 수 있습니다.
간단히 요약하면:
- 페이지 컬렉션:
pages.json에서 중첩 페이지, 기본값, 게시물 유형 동작, 레이아웃, 로더 및 컬렉션 메타데이터를 완전히 정의할 수 있습니다. - Markdown 페이지:
index.md를 페이지 콘텐츠로 사용할 수 있으며,page.json와 함께 쓰거나 frontmatter만으로 사용할 수 있습니다. - 프런트엔드 페이지 레이아웃:
layout.php로 동기화된 페이지 콘텐츠를 감싸고blockstudio_page_tree()및blockstudio_page_content()같은 헬퍼를 사용할 수 있습니다. - 외부 문서 소스: 컬렉션 로더는 로컬 파일 또는 반환된 Markdown/HTML에서 페이지를 생성할 수 있습니다.
- 원본 Markdown 출력: Markdown 페이지 소스를
.md로 제공하거나Accept: text/markdown를 통해 제공할 수 있습니다. - 컬렉션 사용자 지정 게시물 유형: 컬렉션이 별도 테마 측 shim 없이 깔끔한 URL, 자동 재작성 규칙 갱신, 원본 Markdown 경로 및 페이지에서 사용자 지정 게시물 유형으로의 마이그레이션을 관리할 수 있습니다.
- Content Sync:
wp bs content pull,wp bs content push및wp bs content status을 통해 허용 목록에 지정된 게시물, 용어, 관계 및 선언된 메타 참조를 이식 가능한 파일로 관리할 수 있습니다. - 블록 태그 접두사:
<theme-card>같은 프로젝트 접두사를 사용하면 블록별 별칭 없이도 순서가 지정된 네임스페이스에서 블록을 확인할 수 있습니다. - 더 안정적인 동기화: 매니페스트, 로더, 레이아웃, 메타데이터 및 소스 파일의 변경 사항을 감지합니다.
- 런타임 및 편집기 수정: 동적 옵션이 최신 상태로 유지되고, 프로그래밍 방식 렌더링 시 쿼리 블록 클래스가 보존됩니다.
bsui/select가 복잡한 폼에서 더 잘 작동하고, RichText 속성이 편집기에 전달되며, RichText가 있는 반복기 행을 삭제한 뒤 저장해도 변경 사항이 유지됩니다.
파일 기반 페이지
7.4의 대부분은 파일 기반 페이지를 토대로 합니다.
페이지 컬렉션
7.4 이전에는 파일 기반 페이지가 주로 폴더 단위 기능이었습니다. page.json을 만들고 index.php 또는 index.twig를 추가하면 Blockstudio이 해당 페이지 하나를 WordPress에 동기화했습니다.
기존 방식도 계속 사용할 수 있습니다. 7.4에서는 규모가 더 큰 구조를 위한 두 번째 모드가 추가됐습니다.
폴더에 pages.json 매니페스트를 추가하면 해당 폴더가 컬렉션이 됩니다:
pages/
docs/
pages.json
layout.php
index.md
guide/
install/
index.md
reference/
page.json
index.md
{
"collection": "docs",
"title": "Documentation",
"postType": "bs_docs",
"postTypeArgs": {
"label": "Docs",
"rewrite": {
"slug": "docs"
},
"supports": ["title", "editor", "page-attributes"]
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
컬렉션 안의 모든 페이지 소스를 찾아 정규화하고 동기화한 뒤 경로를 기준으로 연결합니다. guide/install의 페이지는 guide의 하위 페이지가 됩니다. guide 페이지가 없으면 Blockstudio이 컨테이너 페이지를 생성해 WordPress 계층이 파일 시스템 구조와 일치하도록 합니다.
컬렉션은 기본 page 게시물 유형이나 자체 게시물 유형을 사용할 수 있습니다. 컬렉션에서 아직 존재하지 않는 게시물 유형을 선언하면 Blockstudio이 postTypeArgs에서 해당 유형을 등록합니다. 매니페스트의 postType도 컬렉션 내 모든 페이지의 기본값이 되므로 프로젝트에서 이를 defaults에 반복해 지정할 필요가 없습니다.
컬렉션 게시물 유형은 컬렉션 슬러그를 공개 URL 기본 경로로 사용합니다. docs 컬렉션은 루트 페이지를 /docs/에서 확인하고, path: "getting-started"가 있는 페이지는 /docs/getting-started/에서 확인하며, 중첩 경로도 같은 기본 경로 아래에서 확인합니다. /docs/docs/ 같은 중복 URL은 표준 위치로 리디렉션됩니다. 컬렉션 게시물 유형의 라우팅이 변경되면 재작성 규칙이 자동으로 갱신되므로 새 컬렉션을 추가해도 퍼머링크를 수동으로 저장할 필요가 없습니다.
이 기능 덕분에 외부 문서, 제품 설명서, 지식 베이스, 페이지 라이브러리를 WordPress에서 자연스럽게 사용할 수 있습니다. 소스는 파일에 그대로 두면서 결과는 실제로 편집할 수 있는 WordPress 콘텐츠로 제공됩니다.
페이지 콘텐츠로서의 Markdown
이제 Markdown를 일급 페이지 소스로 사용할 수 있습니다.
독립형 Markdown 페이지에서는 frontmatter를 사용합니다:
---
name: about
title: About
slug: about
postStatus: publish
---
# About
This Markdown content is synced as native WordPress blocks.
구성 파일과 콘텐츠 파일을 분리하려면 page.json를 index.md와 함께 사용할 수도 있습니다. index.md의 frontmatter로 일치하는 page.json 필드를 재정의할 수 있으며, 알 수 없는 frontmatter 키도 메타데이터로 보존됩니다.
Markdown는 HTML로 변환된 다음 PHP, Twig 및 Blade 템플릿과 동일한 페이지 파서를 거치므로 최종 콘텐츠는 네이티브 블록 마크업이 됩니다.
레이아웃 및 페이지 헬퍼
컬렉션에 layout.php 파일을 포함할 수 있습니다. 프런트엔드에서 Blockstudio가 동기화된 페이지 콘텐츠를 해당 레이아웃으로 감쌉니다.
<main class="docs-layout">
<aside>
<?php foreach (blockstudio_page_tree('docs') as $item) : ?>
<a href="<?php echo esc_url($item['permalink'] ?? '#'); ?>">
<?php echo esc_html($item['title']); ?>
</a>
<?php endforeach; ?>
</aside>
<article>
<?php echo blockstudio_page_content(); ?>
</article>
</main>
새 헬퍼를 사용하면 컬렉션을 구조화된 데이터로 확인할 수 있습니다:
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();
이를 바탕으로 페이지 트리에서 탐색 메뉴를 만들고, frontmatter에서 페이지 메타데이터를 가져오며, 동기화된 WordPress 블록 콘텐츠를 주 콘텐츠 영역으로 표시하는 완전한 문서 사이트 틀을 구축할 수 있습니다.
로더 및 원본 Markdown
컬렉션에 신뢰할 수 있는 로컬 loader.php 파일을 포함할 수 있습니다. 이 파일은 페이지를 직접 반환하거나 Blockstudio가 탐색할 추가 로컬 디렉터리를 지정할 수 있습니다.
<?php
return [
'pages' => [
[
'name' => 'docs-api',
'title' => 'API',
'path' => 'api',
'content' => "# API\n\nGenerated markdown content.",
'contentType' => 'markdown',
],
],
];
패키지 문서 폴더, Markdown 내보내기 파일 또는 페이지 목록을 반환하는 빌드 단계처럼 다른 곳에서 이미 소스를 생성하는 경우 유용합니다.
Markdown 페이지 소스는 원본 Markdown 소스도 제공할 수 있습니다. .md 접미사를 붙여 페이지를 요청하거나 Accept: text/markdown를 전송하세요. 응답에서 frontmatter가 제거되므로 도구가 읽을 수 있는 문서 본문을 받습니다. 컬렉션 게시물 유형에서도 작동하며 /docs.md 및 /docs/getting-started.md 같은 URL을 지원합니다.
콘텐츠 동기화
7.4에서는 프로젝트의 WordPress를 파일로 더 많이 관리하려는 팀을 위한 WP-CLI 워크플로우인 Content Sync도 도입합니다.
wp bs content pull
wp bs content push --dry-run
wp bs content status
Blockstudio는 블록, 필드, 템플릿, 패턴, 파일 기반 페이지를 이미 프로젝트에서 관리합니다. Content Sync는 선택한 데이터베이스 콘텐츠를 이 파일 우선 워크플로우에 추가합니다. 허용 목록에 등록한 게시물, 용어, 관계, 선언된 메타데이터를 파일로 가져와 git에서 검토한 다음 다른 환경으로 푸시할 수 있습니다.
의도적으로 명시적인 설정이 필요합니다. blockstudio.json에서 기능을 활성화하고 관리할 게시물 유형과 택소노미를 허용 목록에 추가한 다음 환경 간에 다시 작성할 메타 참조를 선언해야 합니다.
가져올 때 Blockstudio는 이식 가능한 게시물, 용어, 관계 및 허용 목록의 메타를 테마 파일에 기록합니다. 내보낼 때는 기록 전에 계획을 검증하고 선언된 post, term 및 attachment 참조를 로컬 데이터베이스 ID로 변환합니다. 임의의 정수가 ID라고 추측하지 않습니다.
7.4의 범위는 의도적으로 보수적으로 정했습니다. 게시물, 용어, 용어 관계, 허용 목록의 메타, 이식 가능한 UID, 첨부 파일 매니페스트, 드라이 런, 제거 처리, 잠긴 엔터티 및 상태 보고가 포함됩니다. 택소노미 정의 수집, 미디어 바이너리 복사, 블록 마크업 ID 재작성은 이번 첫 버전에서 제외했습니다.
팀 구성원, 사례 연구, 위치, 문서 항목 또는 기타 구조화된 레코드 같은 선별된 콘텐츠를 버전 관리할 수 있는 깔끔한 방법입니다. 프로덕션 데이터베이스 전체를 마이그레이션할 필요가 없습니다. 파일로 검토할 수 있는 수십 개에서 수백 개 행의 콘텐츠 세트를 대상으로 하며, 구조화되고 변경이 적은 일부 프로젝트에서는 수천 개의 행도 처리할 수 있습니다. 데이터베이스 백업, 전자상거래 및 주문 동기화, 분석, 로그, 양식 제출 또는 그 밖의 대용량 데이터를 대체하는 용도는 아닙니다.
더 안정적인 동기화
이제 Blockstudio가 페이지 소스, 컬렉션 매니페스트, 로더 파일, 레이아웃 파일, 메타데이터 및 관련 경로의 변경 사항을 감지합니다. 이 가운데 무엇이든 변경되면 동기화된 WordPress 페이지가 업데이트됩니다.
페이지 처리 파이프라인은 파일 기반 문서를 실제 프로젝트에서 실용적으로 사용할 수 있도록 세부 사항도 처리합니다:
- Markdown 페이지 소스는 블록 속성을 포함해 네이티브 블록 콘텐츠로 동기화됩니다.
- frontmatter 메타데이터를 프런트엔드 헬퍼와 레이아웃에서 사용할 수 있습니다.
- 컬렉션 페이지는 동기화 후에도 안정적인 식별자를 유지합니다.
- 컬렉션에 속하지 않는 중첩 페이지는 상위 페이지에 연결됩니다.
- 중첩된 비컬렉션 페이지는 가장 가까운 상위
layout.php를 상속할 수 있습니다. - 제거된 컬렉션 소스는 생성된 WordPress 페이지를 정리합니다.
- 컬렉션을
page에서 사용자 지정 게시물 유형으로 변경하면 동기화된 게시물을 중복 생성하는 대신 기존 게시물을 마이그레이션합니다. - 페이지 순서는
menu_order를 통해 저장됩니다.
블록 태그 접두사
이제 블록 태그에서 네임스페이스 접두사를 설정할 수 있습니다. 프로젝트에 짧은 접두사를 하나 등록하면 Blockstudio가 하나 이상의 네임스페이스에서 블록을 확인할 수 있습니다:
add_filter('blockstudio/block_tags/prefixes', function ($prefixes) {
$prefixes['theme'] = ['theme-components', 'bsui'];
return $prefixes;
});
이 설정으로 <theme-card>는 theme-components/card로 확인되고, <theme-button>는 bsui/button을 대체 경로로 사용할 수 있으며, <theme-ui-feature-matrix>는 theme-components/ui-feature-matrix로 확인될 수 있습니다.
프로젝트에서 일회성 재정의가 필요한 경우 명시적인 tag_aliases가 계속 우선 적용됩니다. 알 수 없는 접두사 태그는 변경되지 않으며, 접두사로 확인된 블록에도 기존 블록 태그 허용 및 거부 필터가 적용됩니다.
런타임 및 편집기 수정
7.4에는 실제 프로젝트에서 사용하면서 발견한 문제를 수정한 내용도 포함됩니다.
- 게시물, 용어, 사용자 또는 관련 메타가 변경되어도 쿼리로 채워지는 동적 옵션이 최신 상태로 유지됩니다. 또한
populate.fetch: true쿼리 선택 필드는 편집기에서 검색 결과가 없을 때 최신 옵션을 가져옵니다. - 프로그래밍 방식의
core/query및core/comments블록 태그는 생성된 래퍼 마크업에서className를 보존합니다. - 템플릿 유사 구성 요소는 camelCase 속성을 보존하므로
allowedFormats및withoutInteractiveFormatting같은 속성이 미리 제거되지 않고 편집기 구성 요소에 전달됩니다. bsui/select가 옵션 데이터와 넘치는 메뉴를 더 안정적으로 처리하며, 특히 편집기에서 제어 요소가 많은 경우에 개선됩니다.blockstudio/phpstan는tabs컨테이너 안에 선언된 필드를 인식합니다. 따라서 템플릿, Twig/Blade 및 블록 태그 검증에서 Blockstudio가 프로젝트에서 사용하는 것과 동일한 필드 형태를 이해합니다.- RichText가 있는 반복기 행을 삭제한 뒤 저장하면 변경 사항이 유지됩니다. 오래된 RichText 값으로 삭제한 행이 다시 나타나지 않습니다.
이번 릴리스가 중요한 이유
7.4의 주제는 이식성입니다.
페이지 컬렉션은 문서 사이트 전체를 소스 파일 폴더로 바꿉니다. Markdown 페이지를 사용하면 콘텐츠를 쉽게 작성하고 읽어 올 수 있습니다. Content Sync는 같은 파일 우선 모델을 엄선된 데이터베이스 콘텐츠로 확장하여 게시물, 용어, 관계를 git에 저장하고 환경 간에 이동할 수 있게 합니다. 블록 태그 접두사를 사용하면 템플릿에서 대규모 블록 라이브러리를 쉽게 읽을 수 있습니다.
Blockstudio는 여전히 파일 기반입니다. 블록은 여전히 폴더에 있고 페이지는 여전히 파일입니다. 7.4에서는 프로젝트의 더 많은 부분, 즉 페이지 구조와 선별된 콘텐츠를 파일에 담아 함께 옮길 수 있습니다.