본문으로 건너뛰기

코드로 정의하는 전체 페이지

명령 하나로 템플릿과 Markdown를 WordPress에 동기화하세요.

파일 기반 컬렉션

pages.json를 정의하면 Blockstudio가 그 아래의 모든 소스를 찾습니다. 중첩 경로는 중첩 페이지가 되고, 기본값은 컬렉션에 적용되며, 없는 상위 페이지도 생성할 수 있습니다.

loader.php를 사용해 문서, 지식 베이스 또는 랜딩 페이지에 컬렉션을 활용하고, 외부 폴더를 경로 접두사 아래에 마운트하세요.

컬렉션의 모든 페이지를 하나의 셸로 감싸려면 pages.json 옆에 layout.php 또는 layout.tsx 같은 렌더러 레이아웃을 두고, 사이드바에는 blockstudio_page_tree()을 사용하세요.

pages/docs/pages.json
{
  "collection": "docs",
  "title": "Documentation",
  "postType": "bs_docs",
  "defaults": {
    "postStatus": "publish",
    "templateLock": "contentOnly"
  }
}

명시적 동기화

wp bs pages sync를 실행하면 변경 사항이 적용되고, 변경되지 않은 페이지에는 쓰기 작업이 발생하지 않습니다.

Markdown 소스

index.md를 프런트매터와 함께 사용하거나 page.json와 Markdown 콘텐츠를 짝지어 사용하세요.

원본 Markdown

Markdown 파일 페이지는 URL에 .md를 붙인 경로로 응답하거나, Accept: text/markdown 요청에는 일반 URL로 응답하며, HTML로 돌아가는 canonical 링크를 제공합니다.

컬렉션 로더

외부 문서 폴더를 경로 접두사 아래 컬렉션에 마운트하세요.

사이트 컬렉션

scope가 site인 pages.json는 URL이나 게시물 행을 변경하지 않고 페이지 트리 전체에 공통 기본값을 적용하고 트리를 목록으로 제공합니다.

탐색 도우미

blockstudio_page_tree(), blockstudio_page_children(), blockstudio_current_page() 및 blockstudio_page_content()는 사이드바, 페이지 이동기, 본문을 구성합니다.

컬렉션 및 게시물 유형

컬렉션은 전용 계층형 게시물 유형을 등록할 수 있습니다.

템플릿 잠금

contentOnly, all 또는 insert로 페이지나 개별 블록을 잠그세요.

HTML을 작성해 블록 만들기

<h1>, <p>, <ul> 같은 표준 요소는 코어 블록에 연결됩니다. 다른 모든 블록 이름과 중첩 수준에는 <block>를 사용하세요.

Blockstudio는 전체 페이지 레이아웃을 실제 편집 가능한 WordPress 블록으로 분석합니다.

index.php
<div>
  <h1 blockEditingMode="contentOnly">About Us</h1>
  <p>We build tools for WordPress developers.</p>
  <img src="/team.jpg" alt="Our team" />
</div>

<block name="core/columns">
  <block name="core/column"><h2>Our Mission</h2></block>
  <block name="core/column"><h2>Our Stack</h2></block>
</block>

컴포넌트로 렌더링되는 페이지

page.json에서 page.tsx 같은 항목과 data.php 로더를 지정해 render를 설정하면, 테마나 플러그인이 등록한 페이지 렌더러가 페이지 전체를 그립니다. 동기화는 blockstudio/page 블록 하나를 저장하며, 쇼트코드 같은 WordPress 콘텐츠는 해당 슬롯에 유지됩니다.

렌더러가 반환하는 에셋은 블록 에셋과 동일하게 처리되어 한 번만 출력되므로, 프리렌더링된 페이지에 포함됩니다. blockstudio.dev 자체는 컴포넌트 페이지로 구성됩니다.

pages/legal-notice/page.json
{
  "name": "legal-notice",
  "title": "Legal Notice",
  "slug": "legal-notice",
  "postStatus": "publish",
  "render": { "entry": "page.tsx", "data": "data.php" }
}

게시물이 없는 경로

Blockstudio\Virtual_Routes::register()는 컴포넌트 참조나 카탈로그처럼 게시물을 기반으로 하지 않는 문서를 제공합니다. prefix 및 match를 사용하면 하나의 등록으로 URL 전체군에 응답할 수 있으며, null를 반환하면 URL가 WordPress하도록 할 수 있습니다.

경로는 Blockstudio의 출력 버퍼 안에서 렌더링되므로 해당 블록에 에셋과 Tailwind 출력이 적용됩니다. urls의 경로는 정적 프리렌더링 빌드에 포함되고, Virtual_Routes::urls()는 사이트맵에 해당 경로를 반환합니다.

functions.php
add_action( 'init', function () {
    Blockstudio\Virtual_Routes::register(
        'components',
        function ( $component, string $rest ) {
            get_header();
            echo my_component_page( $component );
            get_footer();
        },
        [
            'prefix' => true,
            'match'  => fn ( string $rest ) => '' === $rest ? 'index' : my_component( $rest ),
            'title'  => fn ( $component ) => my_component_title( $component ),
            'urls'   => fn () => my_component_paths(),
        ]
    );
} );

원하는 시점에 동기화

요청할 때만 페이지 파일 변경 사항이 WordPress에 적용됩니다. wp bs pages sync는 변경된 각 소스를 반영하고, 키가 지정된 편집기 콘텐츠를 유지하며, 파일이 삭제된 페이지를 정리합니다.

지문은 매니페스트, 로더, 레이아웃, 소스를 확인하므로 변경되지 않은 페이지에는 쓰기 작업이 발생하지 않습니다. 배포 시 Pages::reconcile()를 호출해 기계가 읽을 수 있는 보고서를 받습니다.

터미널
# Apply changed sources, keep keyed edits
wp bs pages sync

# Replace managed content from the files
wp bs pages sync --authoritative

# Compare every page and report as JSON
wp bs pages sync --full --format=json

키가 지정된 블록은 콘텐츠를 보존합니다

모든 블록에 key를 추가하세요. 다음 동기화 때 키가 지정된 블록은 템플릿 속성을 기존 사용자 콘텐츠와 병합하고, 키가 없는 블록은 대체됩니다.

배포마다 구조를 발전시키면서 고객 콘텐츠는 그대로 유지하세요.

index.php
<h1 key="title">About Us</h1>
<block name="core/cover" key="hero" url="/hero.jpg">
  <h2>Welcome to our company</h2>
  <p>Edit this content freely.</p>
</block>
<block name="core/columns" key="team">
  <block name="core/column"><h3>Our Team</h3></block>
</block>

템플릿 잠금 및 편집 모드

"all"는 변경을 막고, "contentOnly"은 텍스트 편집을 허용하면서 구조를 잠그며, "insert"는 추가나 삭제 없이 편집 및 순서 변경을 허용합니다.

blockEditingMode로 요소를 재정의하면 잠긴 페이지를 선택적으로 편집할 수 있으며 개별 블록을 비활성화할 수 있습니다.

index.php
<h1>Welcome to Our Product</h1>
<p>The best solution for your needs.</p>
<block name="core/cover" blockEditingMode="disabled" url="/static-banner.jpg">
  <p>Promotional banner</p>
</block>
<block name="core/group" blockEditingMode="default">
  <h2>Customizable Section</h2>
</block>

파일 기반 사이트 편집기 템플릿

templates/에 template.json와 템플릿을 추가하거나 parts/에 part.json를 추가하면, 블록 테마에 파일 기반 wp_template 및 wp_template_part 소스가 제공됩니다.

페이지와 같은 구문을 사용합니다. 사이트 편집기에서 맞춤 설정한 내용은 초기화할 때까지 우선 적용되며, 초기화하면 파일 소스가 다시 적용됩니다.

templates/front-page/index.php
<block name="core/template-part" slug="header" />

<div>
  <h1>Welcome</h1>
  <block name="core/post-content" />
</div>

<block name="core/template-part" slug="footer" />

git의 선택된 데이터베이스 콘텐츠

wp bs content pull은(는) 허용 목록에 있는 글, 용어, 관계, 선언된 메타데이터를 이식 가능한 파일로 내보내고, push은(는) 이를 다른 환경에 적용합니다. 선언된 참조, 부모 항목, 용어 관계는 안정적인 UID로 함께 이동합니다.

페이지 동기화로 관리되는 게시물은 includePageSyncManaged에 포함될 수 있습니다. 해당 파일에는 "bodyOwner": "page-sync"이 포함되므로 Content Sync는 메타데이터를 옮기고 페이지 동기화는 본문을 유지합니다.

blockstudio.json
{
  "content": {
    "enabled": true,
    "id": "default",
    "path": "content",
    "postTypes": ["team_member"],
    "taxonomies": ["category"],
    "meta": {
      "include": ["_my_*"],
      "references": {
        "_thumbnail_id": { "kind": "attachment" },
        "_related_posts": { "kind": "post", "path": "*" }
      }
    },
    "media": "manifest"
  }
}

키가 있는 블록

템플릿이 변경되어도 사용자 콘텐츠를 유지하세요.

편집 모드

페이지 기본값을 설정하고 개별 요소를 재정의하세요.

블록 바인딩

블록을 게시물 메타에 연결하면 동기화 후에도 콘텐츠가 유지됩니다.

게시물 유형 템플릿

templateFor는 해당 유형의 모든 새 게시물에 적용할 시작 블록 구조로 페이지를 지정합니다.

고정 게시물 ID

postId는 페이지를 삭제한 후 다시 동기화할 때 같은 ID를 복원하므로 메뉴와 링크가 계속 작동합니다.

스캐폴드와 잠금

Pages::force_sync()와 함께 sync: false를 사용하면 편집자가 소유할 페이지가 한 번 생성됩니다. Pages::lock() 및 unlock()는 페이지 하나를 동기화 대상에서 제외합니다.

사용자 지정 파서 렌더러

빌더 및 렌더러 필터를 사용하면 블록 태그를 타사 블록의 블록 배열로 변환하거나 코어 블록의 작성 방식을 변경할 수 있습니다.

요소 매핑

HTML 요소를 다른 블록에 매핑하고, 요소의 속성에 따라 블록을 선택하며, 문단 HTML을 콘텐츠 필드로 전달합니다.

사용자 지정 검색 경로

필터를 사용하면 예를 들어 플러그인에서 페이지, 패턴, Site Editor 템플릿의 루트를 추가할 수 있습니다.

논리적 검색 소스

미리보기, 오버레이, 생성된 테마는 하나의 테마 폴더 대신 구성된 파일 목록을 Blockstudio에 전달할 수 있습니다.

안정적인 참조

선언된 게시물, 용어, 첨부 파일 참조는 pull 시 이식 가능한 UID가 되고 push 시 로컬 ID로 확인됩니다.

푸시 전 상태

wp bs content status는 각 엔터티의 상태를 unchanged, would-update, missing-db, conflict, locked 또는 orphaned로 보고하고, 비밀 값처럼 보이는 메타 키에 대해 경고합니다.

검증 및 범위 지정된 푸시

push는 쓰기 전에 전체 계획을 검증하고 잠긴 엔터티를 건너뜁니다. –dry-run은 계획을 표시하며, –prune –yes는 이 콘텐츠 세트의 엔터티만 제거합니다.

버전 관리

Git에서 페이지 파일을 추적하고 여러 환경에 배포하세요.

PHP API

트리, 하위 항목, 메타데이터, 동기화, 잠금, ID에 프로그래밍 방식으로 접근하세요.

Plus

공식 확장 키트

프리미엄 사이트 템플릿, AI 시스템 지침, 비공개 Discord 커뮤니티를 제공합니다. 한 번 구매하면 업데이트를 평생 받을 수 있습니다.

  • 500개 이상의 사이트 템플릿
  • AI 시스템 지침
  • 평생 업데이트
  • 비공개 Discord 커뮤니티