본문으로 건너뛰기

페이지

페이지는 파일 기반 템플릿으로, 데이터베이스에 WordPress 글로 동기화됩니다. 동기화는 명시적으로 수행합니다. 소스 변경 사항을 적용할 때 wp bs pages sync을 실행하거나 Pages API를 호출하세요. 프런트엔드나 WordPress 관리 화면을 불러와도 페이지 전체를 검색하거나 페이지 글을 변경하지 않습니다.

페이지는 단일 page.json 폴더, 독립형 Markdown 또는 pages.json 매니페스트가 있는 컬렉션으로 정의할 수 있습니다. 컬렉션은 문서, 지식 베이스, 랜딩 페이지 라이브러리 또는 파일에서 생성할 중첩 페이지 집합에 유용합니다.

page.json

JSON으로 정의된 페이지에는 page.json 설정 파일을 추가하세요.

JSON
{
  "name": "about",
  "title": "About Us",
  "slug": "about-us",
  "postType": "page",
  "postStatus": "publish",
  "templateLock": "all"
}

속성

속성 유형 기본값 설명
name string 필수 페이지의 고유 식별자
title string 이름에서 자동 생성 페이지 제목
slug string 이름과 동일 페이지의 URL 슬러그
path string "." 컬렉션 내 논리 경로
order integer 0 동기화된 게시물의 메뉴 순서
postType string "page" WordPress 게시물 유형
postStatus string "draft" 새 게시물 상태(publish, draft, pending, private)
postId integer – 페이지를 특정 WordPress 게시물 ID에 고정
blockEditingMode string – 블록 편집 모드: "default", "contentOnly" 또는 "disabled"
templateLock string|false "all" 잠금 모드: "all", "insert", "contentOnly" 또는 false
templateFor string|null null 게시물 유형의 기본 템플릿으로 설정
sync boolean true 일반적인 명시적 조정에서 게시물을 생성하거나 업데이트할지 여부
render string|object|false – 등록된 페이지 렌더러로 페이지 렌더링(컴포넌트 페이지 참조)

page.json, 프런트매터 및 로더 항목에서 인식되는 키에는 blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock 및 title이 있습니다. 위에 나열되지 않은 키는 페이지의 meta 배열에 저장됩니다.

콘텐츠 소스

페이지 정의는 어떤 WordPress 글이 있어야 하는지 결정합니다. 콘텐츠 소스는 해당 글에 어떤 블록 마크업을 쓸지 결정합니다.

페이지 폴더에 page.json이 있으면 Blockstudio은 같은 폴더의 소스 파일을 다음 순서로 찾습니다.

파일 용도
index.php HTML과 비슷한 블록 마크업을 그대로 읽음(PHP 코드는 실행되지 않음)
index.blade.php Blade 템플릿 콘텐츠
index.twig Twig 템플릿 콘텐츠
index.md Markdown 콘텐츠

page.json은 같은 폴더의 파일 대신 인라인 markdown 또는 html를 제공할 수도 있습니다.

JSON
{
  "name": "intro",
  "title": "Intro",
  "markdown": "# Intro\n\nThis page is generated from inline markdown."
}
JSON
{
  "name": "notice",
  "title": "Notice",
  "html": "<h1>Notice</h1><p>This page is generated from inline HTML.</p>"
}

컬렉션은 소스 모드 두 가지를 추가로 지원합니다.

  • 컬렉션 트리에서 직접 검색한 Markdown 파일.
  • loader.php에서 반환된 로더 항목.

로더 항목에는 contentType과 함께 markdown, html 또는 content를 사용할 수 있습니다. 로컬 file 또는 template를 가리킬 수도 있습니다. contentType을 명시적으로 설정하지 않으면 파일 및 템플릿 소스의 유형은 확장자에서 유추됩니다.

지원되는 contentType 값은 php, blade, twig, markdown 및 html입니다. 먼저 Markdown을 HTML로 변환한 다음 네이티브 WordPress 블록으로 파싱합니다. PHP, Blade, Twig 및 HTML 소스는 일반 Blockstudio 페이지 파서를 거칩니다.

코어 블록의 클래스

HTML 요소에 매핑된 class는 코어 블록의 className가 됩니다. 명시적인 코어 블록 태그에는 className를 직접 사용할 수 있습니다. 두 형식 모두 블록의 저장된 래퍼에 클래스를 보존하고, WordPress가 생성하는 클래스도 함께 유지합니다:

HTML
<p class="intro">Introduction</p>
<block name="core/group" className="feature">
  <h2 class="title">Feature</h2>
</block>

두 속성이 모두 있으면 className가 우선합니다. 이 변환은 코어 블록에만 적용됩니다. 사용자 지정 블록 매핑에서는 class 필드가 변경되지 않습니다. is-style-outline 같은 버튼 스타일 클래스는 링크가 아니라 버튼 래퍼에 속합니다.

이전에 동기화한 페이지에 파서 수정 사항을 적용하려면 wp bs pages sync를 실행하세요. 파서 업그레이드는 소스 파일을 수정하지 않아도 다음 명시적 동기화 때 인식됩니다. 잠긴 페이지와 sync: false가 있는 페이지에는 기존 보호가 적용됩니다. 프런트엔드 요청으로는 동기화가 수행되지 않습니다.

직렬화된 WordPress 블록

페이지 및 패턴 소스에는 WordPress 코드 편집기에서 복사한 직렬화된 블록도 포함될 수 있습니다:

HTML
<!-- wp:paragraph {"className":"intro"} -->
<p class="intro">Introduction</p>
<!-- /wp:paragraph -->

원본에 <!-- wp:... --> 블록 구분자가 있으면 Blockstudio는 전체 원본에 WordPress의 기본 블록 파서를 사용합니다. 속성, 중첩 블록, Query Loop 같은 동적 블록, Blockstudio 블록은 직렬화된 구조를 유지합니다. 블록 주석 바깥의 HTML는 기본 자유 형식 HTML로 남으며 추가 블록으로 매핑되지 않습니다. Blockstudio의 HTML 블록 태그를 이 형식과 혼합해도 변환되지 않습니다. 일반 HTML 주석은 직렬화 블록 모드를 선택하지 않습니다.

Markdown 페이지

문장을 파일에 저장하면서 동기화 후 편집 가능한 WordPress 블록 콘텐츠로 만들려면 Markdown을 사용하세요. 동기화 중에 Markdown 소스가 블록 마크업으로 변환됩니다. 동기화된 글에는 원시 Markdown 본문이 아닌 블록이 저장됩니다.

Markdown은 세 가지 방식으로 사용할 수 있습니다.

소스 프런트매터 필요 여부 참고
독립형 pages/example/index.md 예 프런트매터가 페이지의 식별 정보를 제공합니다.
page.json 및 index.md 아니요 page.json이 페이지를 정의하고 Markdown가 콘텐츠를 제공합니다.
컬렉션 내 Markdown 아니요 컬렉션이 파일 위치에서 name 및 path을 유추합니다.

프런트매터가 없는 독립형 index.md은 Blockstudio에 동기화할 페이지 식별 정보가 없어 건너뜁니다. 컬렉션 매니페스트와 파일 경로가 식별 정보를 제공하므로 컬렉션 Markdown에는 프런트매터가 필요하지 않습니다.

Markdown
---
name: about
title: About
slug: about
postStatus: publish
---

# About

This Markdown content is synced as native WordPress blocks.

page.json을 index.md과 함께 사용할 수도 있습니다. 이 경우 page.json가 페이지를 정의하고 index.md가 콘텐츠를 제공합니다. index.md의 프런트매터 값은 일치하는 page.json 값을 재정의합니다.

JSON
{
  "name": "docs-reference",
  "title": "Reference",
  "path": "reference",
  "sync": true
}
Markdown
---
title: API Reference
order: 20
---

# Reference

This page uses `page.json` with Markdown content.

컬렉션 Markdown의 경우 프런트매터에서 재정의하지 않는 한 파일 경로가 논리 페이지 경로가 됩니다.

파일 기본 경로
pages/docs/index.md .
pages/docs/getting-started.md getting-started
pages/docs/guide/install/index.md guide/install
pages/docs/guide/install.md guide/install

알 수 없는 프런트매터 키는 페이지의 meta 배열에 보존됩니다. 이를 통해 section 또는 description 같은 데이터를 추가하고 PHP API에서 읽을 수 있습니다.

Markdown은 GitHub Flavored Markdown로 파싱됩니다. 원시 HTML를 허용하고 안전하지 않은 링크는 제거하며, 명시적 ID가 없는 제목에는 안정적인 ID를 부여합니다. 중첩된 YAML 프런트매터를 사용하려면 번들에 포함된 YAML 파서가 필요합니다.

원시 Markdown

Markdown 파일 소스는 외부 도구와 문서 소비자가 사용할 수 있도록 원본 소스 Markdown를 제공할 수 있습니다. 인라인 Markdown에는 소스 파일이 없으므로 블록으로 동기화되지만 원시 .md 응답은 생성하지 않습니다.

.md 접미사를 붙여 페이지를 요청하세요. 예: https://example.com/docs/reference.md. 또는 일반 페이지 URL에 Accept: text/markdown 헤더를 보내세요:

셸
curl -H "Accept: text/markdown" https://example.com/docs/reference/

응답에서는 프런트매터가 제거됩니다. 원시 Markdown 응답이 성공하면 Content-Type: text/markdown, X-Robots-Tag: noindex 및 정식 Link 헤더를 HTML 페이지로 반환합니다. .md가 없는 경로에는 실제 404를 반환합니다.

정적 사전 렌더링에서도 콘텐츠 협상이 작동합니다. Accept 헤더에 text/markdown이 포함된 요청은 사전 렌더링 저장소나 조기 제공 드롭인에서 처리되지 않으므로 WordPress와 Markdown 핸들러에 도달합니다. 사전 렌더링된 HTML 응답, Markdown도 협상하는 페이지의 HTML, 그리고 Accept을 통해 처리되는 Markdown는 Vary: Accept을 전송하므로 이를 준수하는 캐시는 Vary에 따라 두 응답을 분리합니다. 캐시 키가 URL만 사용하는 CDN에는 이러한 요청의 캐시 우회 규칙이 별도로 필요합니다. Pages::negotiates_markdown( $post_id )는 페이지가 Markdown 요청에 응답하는지 보고합니다.

컬렉션 Markdown은 원시 Markdown에도 같은 URL 구조를 유지합니다.

페이지 URL 원시 Markdown URL
/docs/ /docs.md
/docs/getting-started/ /docs/getting-started.md
/docs/guide/install/ /docs/guide/install.md

blockstudio/pages/serve_markdown 필터로 원시 Markdown 응답을 비활성화하세요.

PHP
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );

Markdown 기반 페이지로 확인되지 않는 .md URL는 경로가 페이지 컬렉션 안에 있을 때만 404를 반환합니다. 어떤 컬렉션에도 속하지 않는 경로에서는 Blockstudio가 요청을 그대로 두어 WordPress 및 다른 플러그인이 처리하도록 합니다.

컴포넌트 페이지

컴포넌트 페이지는 블록으로 저장되는 대신 페이지 렌더러가 렌더링합니다. Blockstudio에는 렌더러가 포함되어 있지 않습니다. 테마나 플러그인이 처리하는 엔트리 파일에 렌더러를 등록합니다. 예를 들어 page.tsx용 React 렌더러를 등록하면 Blockstudio이 페이지, WordPress 게시물 및 렌더링된 슬롯 콘텐츠를 전달해 호출합니다.

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

render은 명시적입니다. index.php과 page.tsx가 있지만 render가 없는 디렉터리는 일반 페이지로 유지되므로 렌더러를 추가해도 기존 페이지가 두 번 렌더링되지 않습니다. 형식은 다음과 같습니다.

값 의미
"page.tsx" 데이터 로더가 없는 엔트리만
{ "entry": "page.tsx", "data": "data.php" } 엔트리 및 데이터 로더
{ "entry": "page.tsx", "renderer": "react" } 명시적 렌더러 ID가 있는 엔트리
false 컬렉션 기본값에 렌더러가 지정되어 있어도 렌더러 없음

경로는 페이지 디렉터리를 기준으로 확인되며, 로더 항목의 경우 컬렉션 루트를 기준으로 확인됩니다. blockstudio/pages/allow_external_loader_path에서 허용하지 않는 한 검색 소스 내부에 있어야 합니다. renderer이 없으면 엔트리의 확장자를 처리하는 렌더러가 사용됩니다. 존재하지 않는 엔트리나 데이터 파일을 지정하는 render, 알 수 없는 렌더러 또는 어떤 렌더러도 처리하지 않는 확장자는 검색 오류입니다. 이 경우 정리 작업이 시작되기 전에 조정이 실패합니다.

동기화가 저장하는 내용

동기화는 blockstudio/page 블록 하나를 저장합니다. 페이지 디렉터리에 index.* 소스도 있으면 해당 소스는 다른 페이지 소스와 마찬가지로 파싱되어 블록의 내부 블록, 즉 슬롯이 됩니다.

HTML
<!-- wp:blockstudio/page /-->

<!-- wp:blockstudio/page -->
<!-- wp:paragraph -->
<p>[download_checkout]</p>
<!-- /wp:paragraph -->
<!-- /wp:blockstudio/page -->

WordPress이 소유하는 숏코드 같은 콘텐츠는 슬롯에 유지합니다. [download_checkout]처럼 숏코드 하나만 있는 소스는 core/shortcode 블록으로 저장되므로 출력 주변에 단락이 생기지 않습니다. 이 콘텐츠는 post_content에 유지되므로 has_shortcode() 검사가 이를 확인할 수 있고, 키가 지정된 슬롯 블록은 중첩된 키 블록과 마찬가지로 편집기 변경 사항과 병합됩니다. 또한 do_shortcode은 렌더러가 숏코드를 감싼 뒤 평소의 the_content 우선순위에서 숏코드를 한 번 확장합니다.

렌더 정의는 이식 가능한 theme: 경로로 게시물에 저장됩니다. 페이지 지문은 정의를 포함하지만 엔트리나 데이터 로더의 바이트는 포함하지 않습니다. page.tsx 또는 data.php를 편집해도 게시물은 바뀌지 않으며, 정적 사전 렌더링 그래프를 통해 방문자에게 변경 사항이 반영됩니다. 이 그래프에는 엔트리, 데이터 로더 및 렌더러가 보고하는 모든 파일이 기록됩니다.

렌더러 등록

blockstudio/pages/renderers 액션에 렌더러를 등록합니다. 이 액션은 요청마다 한 번, 첫 검색 또는 렌더링 전에 실행되므로 wp bs pages sync 요청과 프런트엔드 요청이 동일한 레지스트리를 사용합니다.

PHP
add_action(
	'blockstudio/pages/renderers',
	static function (): void {
		Blockstudio\Page_Renderers::register(
			'react',
			array(
				'extensions' => array( 'tsx' ),
				'layouts'    => array( 'layout.tsx' ),
				'render'     => 'my_theme_render_page',
			)
		);
	}
);

렌더러 ID는 소문자여야 합니다. 하나의 확장자나 레이아웃 이름은 하나의 렌더러에만 속할 수 있으며, layout.php은 Blockstudio 자체 레이아웃으로 유지됩니다. 호출 대상에는 요청 하나가 전달됩니다.

키 값
kind page 또는 렌더러 레이아웃의 경우 layout
renderer 렌더러 ID
entry 절대 엔트리 경로
data 절대 데이터 로더 경로 또는 null
page meta을 포함한 표준 페이지 데이터
post_id WordPress 게시물 ID
slot 렌더링된 슬롯 콘텐츠 또는 레이아웃의 경우 페이지 콘텐츠
context frontend, rest, feed 또는 cli

렌더러는 HTML, 렌더링 시 읽은 파일 및 선택적 에셋을 반환합니다.

PHP
function my_theme_render_page( array $request ): array {
	return array(
		'html'         => '<main>...</main>',
		'dependencies' => array( '/abs/path/to/a/file/the/render/read.tsx' ),
		'assets'       => array( array( 'path' => '/abs/path/to/page.js' ) ),
	);
}

context는 요청 유형에서 가져오며 방문자에게서 가져오지 않으므로, 렌더러가 이를 읽어도 로그인 사용자와 익명 사용자 간의 바이트 동등성이 깨지지 않습니다. 렌더러가 실패하면 예외가 발생하며 페이지는 빈 본문으로 렌더링되지 않습니다. REST 편집기 미리보기에서는 대신 블록에 오류 알림이 표시됩니다. 렌더링이 성공하면 blockstudio/pages/rendered 작업이 페이지, HTML 및 해당 종속 항목을 받습니다.

assets는 페이지에 필요한 스크립트 및 스타일 파일을 나열합니다. 이 파일에는 블록 에셋 처리(*.inline.* 규칙, ES 모듈, 압축 및 ?ver)가 적용됩니다. 페이지는 블록 에셋을 출력하는 것과 동일한 버퍼를 통해 파일을 한 번만 출력하므로 프리렌더링된 페이지에도 해당 파일이 포함됩니다. 에셋은 version을 설정하여 ?ver 값을 대체할 수 있습니다. 렌더러 외부의 코드도 Blockstudio\Assets::register_owner()를 통해 같은 채널을 사용할 수 있으며, 이 함수는 출력할 마커 주석을 반환합니다.

편집기

편집기에서 blockstudio/page는 슬롯이 내부 블록으로 포함된 페이지의 서버 렌더링 미리보기를 표시하며, 이 내부 블록은 페이지의 templateLock을 따릅니다. 이 블록은 삽입하거나 복제할 수 없으며 다른 블록 안에 중첩할 수 없습니다.

페이지 컬렉션

컬렉션은 pages.json 매니페스트가 있는 폴더입니다. 하나의 컬렉션 슬러그 아래 여러 페이지 소스를 묶고, 기본값을 적용하며, 중첩 경로를 지원하고, 전용 글 유형을 자동으로 등록할 수 있습니다.

코드
pages/
  docs/
    pages.json
    layout.php
    index.md
    guide/
      install/
        index.md
    reference/
      page.json
      index.md
    loader.php
JSON
{
  "collection": "docs",
  "title": "Documentation",
  "postType": "bs_docs",
  "postTypeArgs": {
    "label": "Docs",
    "rewrite": {
      "slug": "docs"
    },
    "supports": ["title", "editor", "page-attributes"]
  },
  "defaults": {
    "postStatus": "publish",
    "templateLock": "contentOnly"
  }
}
속성 유형 설명
collection / slug / name string 컬렉션 슬러그입니다. collection는 가장 명확한 형식이며 공개 URL 기본값이 됩니다.
title string 사람이 읽기 쉬운 컬렉션 제목입니다.
postType string 생성된 페이지의 글 유형입니다. 기본값은 page입니다. 존재하지 않으면 Blockstudio이 등록합니다.
postTypeArgs object Blockstudio가 컬렉션 글 유형을 등록할 때 register_post_type()에 전달되는 인수입니다.
defaults object 컬렉션의 모든 페이지에 적용되는 기본 페이지 속성입니다. 기본 render은 페이지 디렉터리에 해당 항목이 있을 때만 페이지에 적용됩니다.
scope string collection(기본값) 또는 site입니다. 사이트 컬렉션을 참조하세요.
meta object 사용자 지정 컬렉션 메타데이터입니다. 알 수 없는 매니페스트 키도 meta에 저장됩니다.

컬렉션 페이지 경로는 논리 경로입니다. path: "guide/install"가 있는 페이지는 guide의 하위 항목으로 동기화되며, 해당 상위 페이지가 있으면 guide는 컬렉션 루트의 하위 항목으로 동기화됩니다.

계층형 컬렉션에 중첩 페이지가 있지만 중간 상위 소스가 없으면 Blockstudio은 해당 경로에 빈 컨테이너 페이지를 생성해 WordPress 계층을 완성합니다. page-attributes 상위 항목을 지원하지 않는 비계층형 글 유형에서는 빈 컨테이너를 생성하지 않습니다. 저장된 컬렉션 경로에 따라 라우팅하므로 guide/install 및 setup/install처럼 끝 부분이 모두 install인 중첩 경로도 함께 사용할 수 있습니다.

컬렉션 글 유형 및 URL

컬렉션 매니페스트에서 postType을 설정하면 컬렉션의 모든 페이지가 해당 글 유형으로 동기화됩니다. defaults 안에 같은 값을 반복할 필요는 없습니다. 개별 페이지는 프런트매터 또는 page.json에서 postType를 재정의할 수 있습니다.

글 유형이 없으면 Blockstudio은 페이지와 유사한 편집기 설정인 show_in_rest: true을 사용해 등록하고 컬렉션 슬러그를 공개 URL 기반 경로로 사용합니다. postTypeArgs으로 등록 인수를 재정의할 수 있습니다. 등록된 컬렉션 글 유형이나 재작성 인수가 변경되면 컬렉션 글 유형의 재작성 규칙이 자동으로 초기화되므로 WordPress 고유주소를 다시 저장할 필요가 없습니다.

컬렉션 URL은 컬렉션 슬러그와 각 페이지의 논리 path를 사용합니다.

소스 경로 공개 URL
path: "." /docs/
path: "getting-started" /docs/getting-started/
path: "guide/install" /docs/guide/install/

이 URL 모델은 계층형 및 비계층형 컬렉션 글 유형 모두에서 작동합니다. 또한 Blockstudio은 /docs/docs/ 또는 /docs/docs/getting-started/ 같은 중복 URL을 표준 URL로 리디렉션합니다.

컬렉션 페이지는 동일한 URL에서 원시 Markdown를 제공합니다(원시 Markdown 참조).

컬렉션을 postType: "page"에서 사용자 정의 글 유형으로 변경하면, Blockstudio은 저장된 페이지 식별자가 일치하는 경우 이미 동기화된 컬렉션 글을 제자리에서 마이그레이션합니다. 따라서 글 ID, 메타데이터, 기존 콘텐츠를 보존하면서 이전 유형의 중복 글 생성을 방지합니다. 오래된 컬렉션 글은 blockstudio/pages/orphan_action 필터에 따라 모든 글 상태에서 정리됩니다.

사이트 컬렉션

"scope": "site"이 있는 매니페스트는 그 아래의 모든 페이지를 그룹화하지만 해당 페이지를 컬렉션 페이지로 만들지는 않습니다. 사이트 페이지 트리의 루트에서 사용하면 기본 설정을 공유하고 blockstudio_page_tree( 'my-site' )로 사이트의 페이지를 나열할 수 있습니다.

JSON
{
  "collection": "my-site",
  "title": "My Site",
  "scope": "site",
  "defaults": {
    "postStatus": "publish",
    "templateLock": "all",
    "render": { "entry": "page.tsx", "data": "data.php" }
  }
}

사이트 컬렉션의 페이지는 매니페스트가 없을 때와 정확히 동일한 정체성을 유지합니다. 따라서 기존 트리에 페이지 하나를 추가해도 글 행이 업데이트되지 않으며, 생성되거나 휴지통으로 이동되는 항목도 없습니다:

  • 키는 전역으로 유지됩니다. Pages::get_page( 'home' )과 저장된 페이지 키가 계속 일치합니다.
  • URL은 WordPress 페이지 URL로 유지됩니다. 컬렉션 재작성 규칙, 고유주소 필터, 이중 URL 리디렉션이 적용되지 않으며 빈 컨테이너 페이지도 생성되지 않습니다.
  • 논리 경로, 슬러그, 상위 항목 및 소스 정체성은 독립형 페이지의 값과 같으며, 레이아웃은 가장 가까운 상위 항목을 기준으로 결정됩니다.
  • 중첩된 pages.json 매니페스트는 각각 자체 컬렉션을 유지하며, 해당 하위 트리는 사이트 컬렉션에서 제외됩니다.
  • 기본값은 페이지별로 적용됩니다. 기본 render은 해당 항목이 디렉터리에 있는 페이지에만 적용되므로, 숏코드 및 Markdown 페이지는 자체 소스를 유지합니다.

컬렉션 로더

컬렉션에는 신뢰할 수 있는 로컬 loader.php을 포함할 수 있습니다. 외부 문서 폴더, 패키지 또는 생성된 매니페스트 등 다른 로컬 소스에서 컬렉션 페이지를 가져올 때 사용하세요.

로더는 명시적인 페이지 검색 및 동기화 중에 실행됩니다. 결정적이고 로컬에서 작동해야 합니다. loader.php에서 원격 콘텐츠를 가져오지 마세요. 그러면 배포 동기화가 해당 서비스에 의존하게 됩니다.

PHP
<?php

return array(
  'meta' => array(
    'source' => 'loader',
  ),
  'paths' => array(
    __DIR__ . '/external-docs',
    array(
      'path' => __DIR__ . '/cli-docs',
      'prefix' => 'cli',
      'meta' => array(
        'doc_set' => 'cli',
      ),
    ),
  ),
  'pages' => array(
    array(
      'name' => 'docs-api',
      'title' => 'API',
      'path' => 'api',
      'content' => "# API\n\nGenerated markdown content.",
      'contentType' => 'markdown',
    ),
    array(
      'name' => 'docs-template',
      'title' => 'Template',
      'path' => 'template',
      'file' => __DIR__ . '/template.md',
    ),
  ),
);

로더는 pages, meta, paths 키가 있는 배열을 반환할 수 있습니다:

키 설명
pages 페이지 배열 목록입니다. 각 페이지는 page.json 및 Markdown 프런트매터와 동일하게 인식되는 키를 지원합니다.
meta 로더가 생성한 모든 페이지의 meta 배열에 병합되는 메타데이터입니다.
paths 이 컬렉션의 일부로 탐색할 추가 로컬 디렉터리입니다. 항목은 문자열이나 경로 객체일 수 있습니다.
render paths에서 찾은 모든 Markdown 페이지에 적용할 렌더 정의입니다.

간단한 형식으로 로더는 페이지 배열의 목록을 바로 반환할 수도 있습니다.

로더 페이지 항목은 다음 방식으로 콘텐츠를 제공할 수 있습니다:

형태 설명
markdown 인라인 Markdown 콘텐츠입니다.
html 인라인 HTML 콘텐츠입니다.
content + contentType 일반 인라인 콘텐츠입니다. contentType은 markdown 또는 html로 해석되어야 합니다.
file 로컬 파일 소스입니다. contentType을 설정하지 않으면 확장자로 유형을 추론합니다.
template file의 별칭입니다.

로더 파일 참조는 PHP, Blade, Twig, Markdown 또는 HTML 소스를 가리킬 수 있습니다. 상대 경로는 컬렉션 루트를 기준으로 해석됩니다. 절대 경로와 컬렉션 루트 바깥의 경로는 blockstudio/pages/allow_external_loader_path 필터가 허용하는 경우에만 사용할 수 있습니다.

로더 페이지의 기본값은 generated: true입니다. 생성된 로더 페이지가 로더 출력에서 사라지면 Blockstudio은 다음 동기화 때 동기화된 글을 고아 항목으로 처리하며, blockstudio/pages/orphan_action 필터에 따라 정리합니다.

paths에 나열된 디렉터리는 일반 컬렉션 폴더처럼 검색됩니다. 이 안에는 Markdown 파일이나 page.json 폴더를 둘 수 있습니다. 해당 경로가 컬렉션 루트 바깥에 있으면 동일한 외부 경로 필터가 적용됩니다.

외부 디렉터리의 고유 논리 경로를 유지하려면 문자열 항목을 사용하세요. 디렉터리를 컬렉션 경로 접두사 아래에 마운트하려면 객체 항목을 사용하세요:

PHP
'paths' => array(
  array(
    'path' => __DIR__ . '/cli-docs',
    'prefix' => 'cli',
    'meta' => array(
      'doc_set' => 'cli',
    ),
  ),
),

이 설정에서는 컬렉션에서 cli-docs/index.md은 path: "cli"이 되고 cli-docs/getting-started.md는 path: "cli/getting-started"이 됩니다. 접두사를 사용하면 생성된 페이지 이름의 충돌도 방지되므로 마운트된 여러 디렉터리에 각각 index.md 또는 getting-started.md를 둘 수 있습니다. page.json 또는 Markdown 프런트매터의 명시적 name 값을 그대로 유지하려면 경로 객체에서 preserveNames을 true로 설정하세요.

경로 객체 속성:

속성 유형 설명
path string 탐색할 로컬 디렉터리입니다. 상대 경로는 컬렉션 루트를 기준으로 해석됩니다.
prefix string 컬렉션 내에서 사용할 선택적 논리 경로 접두사입니다.
preserveNames boolean 접두사 경로로 이름을 생성하는 대신 명시적인 페이지 이름을 유지합니다. prefix이 설정된 경우 기본값은 false입니다.
meta object 이 경로에서 찾은 모든 페이지에 병합되는 메타데이터입니다. 중복 키가 있으면 페이지 수준 메타데이터가 우선합니다.
render string|object 이 경로의 Markdown 페이지에 적용되는 렌더 정의이며, 로더의 render을 재정의합니다.

컴포넌트를 통한 Markdown 렌더링

render을 사용하면 로더가 찾은 Markdown 페이지는 블록으로 저장되는 대신 페이지 렌더러를 통해 렌더링됩니다:

PHP
<?php

return array(
  'paths'  => array( __DIR__ . '/external-docs' ),
  'render' => array(
    'entry' => __DIR__ . '/document.tsx',
    'data'  => __DIR__ . '/document.php',
  ),
);

이 페이지는 계속 Markdown 페이지로 유지됩니다. 콘텐츠 유형, 콘텐츠 경로, .md 응답 및 프런트매터는 변경되지 않습니다. 동기화 과정에서는 파싱된 블록 대신 내부 HTML이 변환된 Markdown인 blockstudio/page 블록 하나를 저장합니다. 컬렉션에서 콘텐츠를 정제하는 경우 이 콘텐츠도 정제되므로 post_content가 문서 텍스트를 유지합니다. 렌더러는 이 HTML을 슬롯으로 받으며 page.content_path에서 소스를 읽을 수 있습니다. 상대 경로는 컬렉션 루트를 기준으로 해석되며, 경로에 적용되는 것과 동일한 외부 경로 필터가 적용됩니다. 프런트매터에서 자체 render 또는 render: false을 설정한 페이지는 제외됩니다.

레이아웃

layout.php 파일은 파일 기반 페이지의 프런트엔드 렌더링을 감쌉니다. WordPress에 저장된 동기화된 post_content을 대체하지 않으며 편집기 캔버스도 감싸지 않습니다. 레이아웃은 단일 페이지 프런트엔드 요청에서만 실행됩니다.

컬렉션의 모든 프런트엔드 페이지를 감싸려면 pages.json 옆에 layout.php을 두세요:

PHP
<?php $current = blockstudio_current_page(); ?>

<main class="docs-layout">
  <aside>
    <?php foreach (blockstudio_page_tree('docs') as $item) : ?>
      <?php $is_current = ($item['post_id'] ?? null) === ($current['post_id'] ?? null); ?>
      <a
        href="<?php echo esc_url($item['permalink'] ?? '#'); ?>"
        <?php echo $is_current ? 'aria-current="page"' : ''; ?>
      >
        <?php echo esc_html($item['title']); ?>
      </a>
    <?php endforeach; ?>
  </aside>

  <article>
    <?php echo blockstudio_page_content(); ?>
  </article>
</main>

blockstudio_page_content()은 WordPress이 일반적으로 the_content를 통해 렌더링하는 페이지 본문을 출력합니다. 레이아웃에서 blockstudio_page_content()을 출력하지 않으면 페이지 콘텐츠가 의도적으로 숨겨집니다.

레이아웃에서는 페이지 도우미 함수를 사용할 수 있습니다:

PHP
blockstudio_current_page();
blockstudio_page_collection('docs');
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_content();

컬렉션에 속하지 않는 중첩 페이지도 pages 트리 내에서 가장 가까운 상위 layout.php을 상속할 수 있습니다. 컬렉션 페이지의 경우 컬렉션 루트 레이아웃이 동기화된 각 글에 저장되고 페이지 지문에 포함되어 감시되므로, 다음 동기화 때 레이아웃 변경 사항이 반영됩니다.

렌더러 레이아웃

layout.tsx처럼 렌더러 항목인 레이아웃을 사용할 수도 있으며, 이 항목은 layouts: ["layout.tsx"]을 등록하는 렌더러에 해당합니다. layout.php와 동일한 위치에서 찾으며, 선택적으로 함께 둘 수 있는 layout.data.php은 데이터 로더입니다. 렌더링 시 렌더러는 kind: "layout"와 렌더링된 페이지 콘텐츠를 slot로 받으며, layout.php과 동일한 the_content 우선순위가 적용됩니다. 디렉터리에는 layout.php 또는 렌더러 레이아웃 하나만 둘 수 있으며, 둘 다 있으면 탐색 오류가 발생합니다. 레이아웃이 실패하면 blockstudio/pages/layout_error가 실행되고 페이지 콘텐츠는 래핑되지 않은 상태로 남습니다. layout.php의 경우도 마찬가지입니다.

블록 편집 모드

blockEditingMode 속성은 편집기에서 블록을 편집하는 방식을 제어합니다. 페이지 수준 기본값은 page.json에 설정하고 템플릿에서 요소별로 재정의하세요:

JSON
{
  "name": "about",
  "title": "About Us",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<h1 blockEditingMode="contentOnly">Editable Title</h1>
<p>This paragraph inherits "disabled" from the page default.</p>
<block name="core/buttons" blockEditingMode="default">
  <block name="core/button" url="/contact">Fully editable button</block>
</block>
값 설명
"default" 전체 편집. 블록 선택, 이동, 편집이 가능합니다
"contentOnly" 텍스트만 편집. 블록 텍스트는 편집할 수 있지만 설정과 구조는 잠깁니다
"disabled" 편집 불가. 블록은 완전히 비대화형 상태가 됩니다

요소별 재정의는 모든 요소(<h1>, <p>, <div> 등) 또는 <block> 요소에 HTML 속성으로 설정합니다. 재정의된 요소의 상위 컨테이너 블록은 자식 요소에 계속 접근할 수 있도록 자동으로 contentOnly로 설정됩니다. 이 계단식 적용은 재정의된 요소에서 페이지 루트까지 거슬러 올라가므로, 편집 가능하게 만들 요소에만 blockEditingMode을 설정하면 됩니다.

템플릿 잠금

templateLock 속성은 편집기에서 사용자가 페이지를 편집하는 방식을 제어합니다:

값 추가/삭제 이동 콘텐츠 편집
"all" 아니요 아니요 아니요
"insert" 아니요 예 예
"contentOnly" 아니요 아니요 예
false 예 예 예

templateLock이 설정되면 Blockstudio은 편집기 UI를 통한 블록 잠금 해제를 비활성화합니다.

가상 경로

데이터에서 생성한 구성 요소 참조, 카탈로그 또는 계정 영역처럼 글이 없는 문서도 있습니다. 직접 template_redirect을 연결하는 대신 가상 경로로 등록하세요:

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(),
        ]
    );
} );

경로는 사이트 홈을 기준으로 한 상대 경로입니다. prefix를 사용하면 해당 경로 아래의 모든 경로도 처리하며, match는 나머지 경로(라우트 자체의 경우 빈 문자열)를 받아 렌더 콜백이 받는 값을 반환하거나 null를 반환해 URL가 WordPress하도록 두며, 그러면 평소처럼 404에 응답합니다. 렌더 콜백은 문서를 출력하거나 문자열로 반환합니다. title는 문자열이거나 일치 값을 받는 클로저입니다.

일치하는 요청의 경우 Blockstudio은 WordPress이 404을 감지하지 못하게 하고 redirect_canonical가 리디렉션하지 못하게 합니다. 주 쿼리가 보고하는 단일 페이지 상태를 지우고 상태 코드(기본값은 status, 200)를 전송한 뒤 우선순위 Virtual_Routes::PRIORITY의 template_redirect에서 렌더링합니다. 이는 Blockstudio의 출력 버퍼가 Assets::BUFFER_PRIORITY에서 열린 직후이므로, 완성된 문서에는 다른 페이지와 마찬가지로 블록 에셋, 번들로 묶인 UI 에셋, 컴파일된 Tailwind가 포함됩니다. 또한 우선순위 10의 redirect_canonical보다 먼저 실행됩니다. 전체 문서를 직접 렌더링하는 핸들러도 Assets::BUFFER_PRIORITY 이후에 실행되어야 합니다. 그렇지 않으면 해당 처리가 건너뛰어집니다. urls의 경로(기본적으로 접두사 경로가 아닐 때는 경로 자체)는 정적 사전 렌더링 빌드에 추가되며, Virtual_Routes::urls()는 사이트맵용 절대 URL로 이 경로를 반환합니다. Virtual_Routes::match( $path )은 요청과 같은 방식으로 경로를 확인합니다.

동기화 동작

페이지 글은 명시적 동기화 작업을 통해서만 변경됩니다:

셸
wp bs pages sync

이 명령은 전체 소스 목록을 검색하고, 변경된 글을 만들거나 업데이트하며, 확인된 고아 항목을 제거하고, 컬렉션 라우팅과 컴파일된 templateFor 구성을 새로 고친 뒤 변경 사항을 보고합니다. 키가 지정된 편집기 콘텐츠를 보존하는 대신 관리되는 콘텐츠를 교체하려면 --authoritative을 추가하고, 저장된 소스 식별자와 관계없이 이 실행을 전체 조정으로 보고하려면 --full를 추가하세요:

셸
wp bs pages sync --authoritative --full

일반 프런트엔드, 관리자, AJAX, REST, cron 및 일반 WP-CLI 부트스트랩 요청은 전체 페이지 검색을 실행하거나 관리 대상 조정 목록을 조회하거나 페이지 글을 쓰지 않습니다. 마지막 명시적 작업에서 저장한 기존 동기화 WordPress 글과 간결한 컬렉션 및 글 유형 템플릿 구성을 사용합니다. 초기 설치 또는 업그레이드 시 라우팅 메타데이터를 복원하기 위해 컬렉션 매니페스트를 한 번 검색할 수 있습니다. 이 읽기 전용 부트스트랩은 콘텐츠를 동기화하지 않습니다. 인증된 옵트인 Canvas 새로 고침 엔드포인트는 명시적 작성 API입니다. Canvas는 작업 공간이 열릴 때 한 번 호출하므로 새로 추가되거나 변경된 소스가 초기 목록에 표시됩니다. 라이브 모드는 페이지 소스 변경을 감지할 때 동일한 경계를 호출합니다.

이제 Blockstudio\Pages::init()은 요청 시점 훅만 등록합니다. 이전에 이 메서드에 force 인수를 전달하던 통합은 대신 Blockstudio\Pages::reconcile()를 호출하거나 wp bs pages sync을 실행해야 합니다.

수동 편집 후 페이지가 덮어쓰이지 않도록 하려면 page.json에서 "sync": false을 설정하세요.

이식 가능한 소스 위치

동기화된 테마 파일은 설치 경로를 절대 경로로 저장하는 대신 테마 기준 상대 위치로 저장됩니다. 자식 테마 파일과 부모 테마 파일은 상대 파일 이름이 같더라도 서로 다른 정체성을 유지합니다. 페이지 헬퍼는 현재 요청에 대해 해석된 절대 template_path, content_path, layout_path 및 directory 값을 계속 반환합니다.

이렇게 하면 CLI 동기화와 웹 요청에서 서로 다른 파일 시스템 루트를 사용할 수 있습니다. 예를 들어 제한된 호스팅 환경에서도 Markdown 응답, 레이아웃, 편집기 Tailwind 스캔 또는 사전 렌더링 소스 추적이 깨지지 않습니다. 테마 디렉터리 이름이 바뀌지 않았다면 기존 절대 테마 경로는 읽을 때 새 루트에 맞게 조정됩니다. 이를 읽기 위해 동기화, 데이터베이스 마이그레이션 또는 요청 시점의 메타데이터 쓰기가 필요하지 않습니다. 다음 명시적 동기화에서 이식 가능한 위치가 저장됩니다.

개발 체크아웃 디렉터리를 가리키는 경우처럼 테마 디렉터리가 심볼릭 링크이면, 소스를 심볼릭 링크 경로로 읽든 대상 경로로 읽든 동일한 theme: 위치가 저장되며, 설정된 테마 디렉터리를 기준으로 경로가 확인됩니다.

활성 자식 테마와 부모 테마 바깥의 파일도 설정된 절대 경로를 통해 계속 지원되며, PHP의 open_basedir 제한이 적용됩니다. 이러한 파일은 자동으로 재배치되지 않습니다. 외부 소스를 이동한 뒤에는 설정된 경로를 업데이트하고 명시적으로 동기화하세요.

게시물 필드 소유권

postStatus에서 초기 상태를 설정합니다. 이후 동기화에서는 --authoritative을 사용하는 경우에도 기존 초안, 검토 대기, 비공개, 게시됨, 예약됨 상태를 유지합니다. 파일에 postStatus: "publish"라고 적혀 있다는 이유만으로 초안이 다시 게시되지는 않습니다. 기존 고아 항목 복구 동작은 그대로입니다. 명시적 동기화 시 소스가 있으면 관리 대상 휴지통 게시물을 복원합니다. 이 복원을 방지하려면 페이지를 잠그거나 동기화를 비활성화하세요.

파일은 제목, 슬러그, 게시물 유형, 상위 항목 및 설정된 메뉴 순서를 계속 관리합니다. WordPress에서 이를 수정해도 소스 정의는 바뀌지 않습니다. 다음 명시적 동기화에서 파일의 값이 다시 적용되고, 영향을 받는 필드가 pages.<name>.overwritten에 표시되며, CLI 표 출력에 경고가 포함됩니다. 동기화 사용자가 게시할 수 없는 경우 대기 중인 게시물의 빈 슬러그를 허용하는 동작을 포함해 WordPress의 기본 권한이 계속 적용됩니다.

서로 다른 상태 정책을 명시적으로 관리하는 통합에는 blockstudio/pages/update_post_data을 사용하세요. 키가 지정된 블록은 편집기가 관리하는 블록 콘텐츠를 보존하지만, 키가 게시물의 제목이나 슬러그 소유권을 바꾸지는 않습니다.

컬렉션 페이지의 지문에는 매니페스트, 로더, 페이지 소스, 레이아웃 파일, 메타데이터 및 관련 소스 경로가 포함됩니다. 다음 명시적 동기화에서 해당 입력의 변경 사항이 적용됩니다.

컬렉션 소스가 제거되면 Blockstudio은 생성된 페이지를 삭제하므로 소스 파일이 사라진 뒤에도 오래된 컬렉션 페이지가 남지 않습니다. 기본적으로 고아 컬렉션 페이지는 휴지통으로 이동합니다. trash, delete 또는 keep를 반환하려면 blockstudio/pages/orphan_action을 사용하세요.

프런트엔드 요청에서 Blockstudio은 이미 동기화된 게시 글을 사용해 페이지 레지스트리를 초기화합니다. 초안 및 비공개 페이지는 관리자와 동기화 컨텍스트에서 사용할 수 있지만, 프런트엔드 도우미는 게시된 페이지만 초기화합니다.

배포 조정

Blockstudio\Pages::reconcile()은 PHP 배포 진입점입니다. 필요한 전체 목록을 검색하고 소스 지문과 동기화 엔진 지문을 비교한 뒤 기계 판독 가능한 보고서를 반환합니다:

PHP
$report = Blockstudio\Pages::reconcile([
  'authoritative' => true,
  'plan_valid' => true,
  'source' => [
    'commit' => $commit,
    'dirtyHash' => $dirtyHash,
  ],
  'renames' => [
    [
      'from' => 'pages/old/index.php',
      'to' => 'pages/new/index.php',
    ],
  ],
]);

보고서에는 discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, 페이지별 결과, 검색 오류 및 결정적 sourceIdentity이 포함됩니다.

잠긴 페이지에는 status: "locked"이 있으며 변경되지 않은 페이지와 별도로 집계됩니다. removedPages에는 삭제된 각 페이지의 name, key, postId 및 실제 action(trash 또는 delete)가 표시됩니다. 유지된 게시물이나 이미 휴지통에 있던 게시물은 새로 삭제된 항목으로 집계되지 않습니다. CLI 표 출력에는 생성, 업데이트, 잠금, 삭제 및 콘텐츠 보존 페이지와 각 게시물 ID도 표시됩니다.

파싱 및 키 기반 병합 후 최종 게시물이 동일하면 wp_update_post()을 호출하거나 post_modified을 변경하거나 버전을 만들거나 게시물 업데이트 훅을 실행하지 않습니다. 결과는 unchanged입니다. 소스의 콘텐츠가 편집기 관리 키 지정 콘텐츠와 다르면 preserved: true에서 해당 결정을 표시하며, 최상위 preserved 수에 이 항목이 포함됩니다. 다음 변경 없는 동기화가 아무 작업도 하지 않도록 새 소스 지문과 관리 메타데이터는 계속 기록됩니다. preserved는 전용 상태가 아니라 추가 플래그입니다. 페이지에서 키 지정 콘텐츠를 보존하면서 파일이 관리하는 제목을 업데이트하거나 다른 블록을 추가할 수 있습니다.

authoritative: true은 페이지 동기화 잠금을 해제할 수 있으며, 키가 지정된 편집기 콘텐츠를 보존하는 대신 파일 정의의 콘텐츠로 교체합니다. 일반적인 명시적 동기화에서는 false 상태로 두세요. plan_valid: false, full: true, broad: true, 이전 소스 식별자의 누락 또는 변경된 동기화 엔진 지문은 해당 실행을 전체 조정으로 표시합니다(보고서의 fullReconciliation). 어느 경우든 각 실행은 전체 목록을 비교합니다. Git 이름 변경 기록은 식별 힌트일 뿐입니다. 전체 목록 비교를 대체하지 않습니다.

지문이 같고 런타임 경로도 변경되지 않았다면 글이나 글 메타데이터를 쓰지 않으며 업데이트 훅도 실행하지 않습니다. 변경되지 않은 소스가 새 릴리스 디렉터리로 이동하면 조정 작업은 저장된 템플릿, 콘텐츠, 레이아웃 및 디렉터리 경로만 새로 고칩니다. post_content이나 글 수정 시각은 업데이트하지 않습니다. 관리 대상 페이지의 누락 항목은 검색 오류나 페이지 쓰기 오류 없이 전체 조정 작업이 완료된 후에만 제거됩니다.

직접 API 조정을 실행해도 배포 성공으로 표시되지는 않습니다. 일치하는 정적 아티팩트와 경로를 활성화하고 확인한 뒤 반환된 식별자를 명시적으로 저장하세요:

PHP
Blockstudio\Pages::store_successful_source_identity(
  $report['sourceIdentity']
);

wp bs pages sync은 성공적으로 실행된 후 반환된 식별자를 저장합니다. 일반 WP-CLI 부트스트랩은 저장된 컬렉션 글 유형과 재작성 규칙만 등록합니다. 페이지를 검색하거나 동기화하지 않습니다.

글 ID 고정

기본적으로 WordPress은 글 ID를 자동 할당합니다. 페이지를 삭제한 후 다시 만들면 ID가 바뀌어 메뉴나 하드코딩된 링크 같은 외부 참조가 끊어집니다.

페이지를 특정 ID로 고정하려면 postId을 사용하세요:

JSON
{
  "name": "about",
  "title": "About Us",
  "postId": 42
}

페이지를 만들 때 Blockstudio은 import_id를 통해 ID를 WordPress로 전달합니다. 해당 ID를 사용할 수 있으면 WordPress이 정확히 그 ID를 사용합니다. 관련 없는 다른 글이 이미 해당 ID를 사용 중이면 WordPress은 새 ID를 자동으로 할당하고 별도 알림을 표시하지 않습니다.

기존 페이지를 찾을 때 Blockstudio은 메타 또는 슬러그를 확인하기 전에 먼저 고정된 ID를 확인합니다. 따라서 페이지를 삭제한 후 다시 동기화하면 동일한 ID를 되찾습니다.

키 기반 블록 병합

기본적으로 템플릿 파일이 변경되면 Blockstudio은 새 템플릿으로 글 콘텐츠 전체를 교체합니다. 따라서 WordPress 편집기에서 변경한 내용은 모두 사라집니다.

템플릿 동기화 사이에 사용자 편집 내용을 보존하려면 블록에 key 속성을 추가하세요. 템플릿에 키가 지정된 블록이 있으면 Blockstudio은 기존 글 콘텐츠를 교체하는 대신 템플릿 변경 사항과 병합합니다.

키 추가

모든 HTML 요소 또는 <block> 요소에 key 속성을 사용하세요:

HTML
<h1 key="title">Default Title</h1>
<p key="intro">Default intro text.</p>

<div key="features">
  <p>First feature.</p>
  <p>Second feature.</p>
</div>

<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
  <h2>Hero Title</h2>
  <p>Hero description.</p>
</block>

<block
  name="acme/testimonial"
  key="featured-quote"
  quote="Default quote"
/>

키는 전체 템플릿에서 고유해야 합니다. 키 하나는 블록 전체와 그 콘텐츠를 모두 보호합니다. 키가 지정된 상위 블록 안의 개별 자식 요소에는 키를 지정할 필요가 없습니다. 템플릿 업데이트 사이에 키가 지정된 블록을 원하는 위치나 중첩 수준으로 이동해도 사용자 콘텐츠는 계속 보존됩니다.

키는 Blockstudio 사용자 정의 블록에서도 동일하게 작동합니다. key은 구조적인 페이지 동기화 메타데이터이며, 사용자 정의 필드 값은 일반 Blockstudio 속성으로 유지됩니다. 편집기에서 이러한 필드를 변경하면 이후 템플릿 동기화 시 편집기 값은 유지하면서 서로 독립적인 템플릿 변경 사항은 계속 적용됩니다. 키가 사용자 정의 필드 데이터 안에 들어 있던 이전 버전에서 만든 페이지는 다음 동기화 때 자동으로 마이그레이션됩니다.

병합 작동 방식

템플릿 파일이 변경되고 페이지가 다시 동기화되면:

블록 동작
키가 지정된 블록 사용자 콘텐츠와 Blockstudio 필드 값이 보존됩니다. 템플릿이 관리하는 속성과 구조는 적용됩니다.
키가 지정되지 않은 블록 템플릿 버전으로 완전히 교체됩니다(키가 없을 때와 동일).

예시

키가 지정된 블록의 사용자 편집 내용은 보존됩니다:

  1. 템플릿에서 <p key="intro">Default intro.</p>을 정의합니다.
  2. 사용자가 편집기에서 단락을 "맞춤 소개 문구."로 수정합니다.
  3. 개발자가 템플릿을 업데이트하고 새 블록을 추가하며 레이아웃을 변경합니다.
  4. 동기화 시 단락에는 "맞춤 소개 문구."가 유지되고 새 레이아웃이 적용됩니다.

템플릿의 속성은 계속 적용됩니다:

  1. 템플릿에 key="hero"이 지정된 표지 블록과 url 속성이 있습니다.
  2. 개발자가 표지의 url 속성을 새 배경 이미지로 변경합니다.
  3. 동기화 시 새 배경 이미지가 적용되지만 표지 안의 사용자 콘텐츠 편집 내용은 보존됩니다.

예외 상황

시나리오 동작
템플릿에 새 키 지정 블록 추가 템플릿의 기본 콘텐츠로 표시됩니다
템플릿에서 키 지정 블록 제거 글에서 삭제됩니다
블록 유형 변경(동일한 키) 템플릿이 전적으로 우선하며 콘텐츠는 병합되지 않습니다
중복 키 두 번째 항목은 키가 지정되지 않은 것으로 처리됩니다
템플릿에 키가 없음 전체 교체됩니다(키가 없을 때와 동일한 동작)
강제 동기화 전체 교체되며 키는 무시됩니다
잠긴 글 동기화되지 않습니다

편집 제어와 함께 사용

키, templateLock 및 blockEditingMode을 함께 사용하면 클라이언트가 할 수 있는 작업을 세밀하게 제어할 수 있습니다. 다음은 일반적인 작업 방식입니다.

완전히 잠긴 페이지

개발자가 모든 것을 제어합니다. 페이지는 클라이언트가 전혀 건드릴 수 없는 정적 레이아웃입니다. 법률 페이지, 서비스 약관 또는 코드로만 변경해야 하는 페이지에 유용합니다.

JSON
{
  "name": "terms",
  "title": "Terms of Service",
  "templateLock": "all"
}
HTML
<h1>Terms of Service</h1>
<p>Last updated: January 2025</p>
<p>These terms govern your use of our service...</p>

키는 필요하지 않습니다. 템플릿이 유일한 기준입니다. 동기화할 때마다 페이지 전체를 덮어씁니다.

레이아웃은 잠그고 콘텐츠는 편집 가능

가장 일반적인 방식입니다. 클라이언트가 블록을 추가, 삭제 또는 재배치하지 못하도록 페이지 구조를 잠그되 특정 위치의 텍스트는 편집할 수 있게 합니다. 키를 사용하면 템플릿이 업데이트되어도 편집 내용이 유지됩니다.

JSON
{
  "name": "landing",
  "title": "Landing Page",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
  <h1 blockEditingMode="contentOnly">Edit This Title</h1>
  <p blockEditingMode="contentOnly">Edit this description.</p>
</block>

<div key="features">
  <h2>Features</h2>
  <p blockEditingMode="contentOnly">Editable feature intro.</p>
</div>

<block name="core/buttons">
  <block name="core/button" url="/contact">Contact Us</block>
</block>

클라이언트는 히어로 제목, 설명, 기능 소개만 편집할 수 있습니다. 다른 항목은 편집할 수 없습니다. 버튼 텍스트, URL, 표지 배경 이미지는 개발자가 제어합니다. 개발자가 템플릿을 업데이트해도(e.g., 버튼을 하나 더 추가해도) 키가 지정된 섹션에는 클라이언트의 텍스트가 유지됩니다.

콘텐츠를 유지하며 템플릿 확장

시간이 지나며 커지는 페이지에 적합합니다. 개발자가 템플릿에 새 섹션을 추가하면 동기화할 때마다 클라이언트가 이미 맞춤 설정한 내용은 건드리지 않고 새 콘텐츠를 추가합니다.

HTML
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
  <h2>Our Services</h2>
  <p>We offer great things.</p>
</div>
HTML
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
  <h2>Our Services</h2>
  <p>We offer great things.</p>
</div>
<div key="testimonials">
  <h2>Testimonials</h2>
  <p>What our clients say.</p>
</div>
<block name="core/buttons">
  <block name="core/button" url="/contact">Get in Touch</block>
</block>

동기화하면 새로운 추천사 섹션과 버튼이 표시됩니다. 제목, 소개, 서비스에 대한 클라이언트의 수정 내용은 그대로 유지됩니다.

한 번만 스캐폴드 생성

시작 구조가 있는 페이지를 만든 다음 완전히 인계하세요. sync을 false로 설정하면 일반 동기화에서 페이지를 생성하거나 업데이트하지 않으며, Blockstudio\Pages::force_sync('blog')로 한 번만 만들 수 있습니다. 그 후에는 클라이언트가 페이지를 완전히 소유합니다.

JSON
{
  "name": "blog",
  "title": "Blog",
  "sync": false
}
HTML
<h1>Our Blog</h1>
<p>Welcome to our blog. Start writing!</p>

wp bs pages sync은 이 페이지를 건너뛰므로 force_sync()로 한 번 생성합니다. 그 후 클라이언트는 블록을 자유롭게 추가, 삭제, 재배치할 수 있습니다. 템플릿 변경 사항은 무시됩니다.

블록 바인딩

키 기반 병합의 대안으로 WordPress 코어의 블록 바인딩API을 사용해 블록을 글 메타데이터에 연결할 수 있습니다. 이는 Blockstudio 기능이 아니라 기본 제공되는 WordPress API입니다. Blockstudio은 metadata 속성을 생성된 블록 마크업에 전달하기만 합니다. 콘텐츠는 블록 마크업이 아닌 글 메타데이터에 저장되므로 편집기에서 innerHTML이 아니라 메타데이터를 읽습니다. 따라서 템플릿 동기화에서 마크업을 자유롭게 덮어쓸 수 있습니다.

모든 HTML 요소 또는 <block> 요소에 metadata 속성을 전달하세요:

HTML
<h1
  metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_title"}}}}'
>
  Default Title
</h1>

<p
  metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_description"}}}}'
>
  Default description text.
</p>

<img
  metadata='{"bindings":{"url":{"source":"core/post-meta","args":{"key":"hero_image"}},"alt":{"source":"core/post-meta","args":{"key":"hero_image_alt"}}}}'
/>

메타 키는 show_in_rest이 활성화된 상태로 등록해야 합니다:

PHP
register_post_meta( 'page', 'hero_title', array(
    'show_in_rest'  => true,
    'single'        => true,
    'type'          => 'string',
    'default'       => 'Default Title',
) );

키와 바인딩 비교

항목 키 바인딩
콘텐츠 저장 위치 블록 마크업(post_content) 글 메타데이터(wp_postmeta)
템플릿 동기화 후 유지 예(키 기준 병합) 예(데이터가 메타데이터에 저장됨)
WP_Query로 조회 가능 아니요 예(meta_query)
REST API에서 사용 가능 아니요 예
등록 필요 여부 아니요 예(register_post_meta)
사용자가 블록 이동 가능 아니요(템플릿이 구조를 다시 적용함) 아니요(템플릿이 구조를 다시 적용함)

한 템플릿에서 두 방식을 함께 사용할 수 있습니다. 블록 구조가 중요한 섹션(e.g., 자식이 여러 개인 그룹)에는 키를 사용하세요. 블록 편집기 외부에서도 데이터에 접근할 수 있어야 하는 개별 필드에는 바인딩을 사용하세요.

글 유형 템플릿

templateFor을 사용해 페이지를 글 유형의 기본 템플릿으로 설정하세요:

JSON
{
  "name": "product-template",
  "title": "Product Template",
  "templateFor": "product",
  "templateLock": "insert"
}

해당 유형의 새 글은 정의된 블록 구조로 시작합니다.

사용자 지정 경로

기본적으로 Blockstudio은 get_template_directory() . '/pages'을 검색합니다. 필터로 경로를 추가하세요:

PHP
add_filter( 'blockstudio/pages/paths', function( $paths ) {
    $paths[] = get_stylesheet_directory() . '/custom-pages';
    $paths[] = MY_PLUGIN_DIR . '/pages';
    return $paths;
} );

여러 루트의 파일을 조합하는 런타임 통합 기능은 파일 시스템 검색을 논리적 검색 소스로 대체할 수 있습니다. 페이지 매니페스트, 레이아웃, 로더, 소스 템플릿은 선택된 파일이 서로 다른 루트에 있더라도 논리 경로로 확인됩니다.

필터와 액션

페이지 검색, 동기화, 컬렉션 라우팅에는 다음 확장 지점이 있습니다:

훅 유형 설명
blockstudio/pages/paths 필터 Blockstudio에서 페이지 소스를 검색할 디렉터리를 추가합니다.
blockstudio/pages/collection_post_type_args 필터 컬렉션 CPT의 register_post_type() 인수를 조정합니다.
blockstudio/pages/template_candidates 필터 페이지 소스로 간주할 템플릿 파일 이름을 조정합니다.
blockstudio/pages/serve_markdown 필터 원시 Markdown 응답을 활성화하거나 비활성화합니다.
blockstudio/pages/orphan_action 필터 고아 항목 정리 시 trash, delete 또는 keep을 반환합니다.
blockstudio/pages/docs_allowed_html 필터 생성된 Markdown 문서 콘텐츠에 허용되는 HTML를 조정합니다.
blockstudio/pages/allow_external_loader_path 필터 로더 paths가 컬렉션 루트 바깥에 있도록 허용합니다.
blockstudio/pages/manifest_scan_interval 필터 업그레이드 중 유지된 런타임 설정의 기반이 될 수 있는 레거시 7.6.2 이전 매니페스트 캐시의 최대 보존 기간을 설정합니다.
blockstudio/pages/create_post_data 필터 동기화된 페이지를 생성하기 전에 게시물 데이터를 수정합니다.
blockstudio/pages/update_post_data 필터 동기화된 페이지를 업데이트하기 전에 게시물 데이터를 수정합니다.
blockstudio/pages/sync_engine_inputs 필터 조정 범위를 한 번 의도적으로 넓힐 파서, 매핑 또는 마이그레이션 버전을 추가합니다.
blockstudio/pages/post_created 액션 동기화된 페이지 게시물이 생성된 후 실행됩니다.
blockstudio/pages/post_updated 액션 동기화된 페이지 게시물이 업데이트된 후 실행됩니다.
blockstudio/pages/synced 액션 페이지 레지스트리 동기화가 완료된 후 실행됩니다.
blockstudio/pages/reconciled 액션 기계에서 읽을 수 있는 보고서와 함께 명시적 조정이 끝난 후 실행됩니다.
blockstudio/pages/renderers 액션 Blockstudio\Page_Renderers::register()에 페이지 렌더러를 등록합니다. 요청마다 한 번 실행됩니다.
blockstudio/pages/rendered 액션 페이지, 해당 HTML 및 종속 항목과 함께 구성 요소 페이지가 렌더링된 후 실행됩니다.
blockstudio/pages/layout_error 액션 레이아웃을 렌더링할 수 없을 때 오류, 레이아웃 경로 및 페이지와 함께 실행됩니다.

PHP API

PHP
// Get all registered pages.
$pages = Blockstudio\Pages::pages();

// Get pages from one collection.
$docs = Blockstudio\Pages::pages('docs');

// Get the pages of one collection, sorted (same result as pages('docs')).
$docs = Blockstudio\Pages::in_collection('docs');

// Get a nested page tree.
$tree = Blockstudio\Pages::tree('docs');

// Get direct children for a page.
$children = Blockstudio\Pages::children('docs-guide', 'docs');

// Get collection metadata.
$collection = Blockstudio\Pages::collection('docs');

// Get a specific page.
$page = Blockstudio\Pages::get_page('about');

// Get the WordPress post ID for a page.
$postId = Blockstudio\Pages::get_post_id('about');

// Force sync a page explicitly (ignores fingerprints, locks, and sync: false).
Blockstudio\Pages::force_sync('about');

// Force sync all discovered pages explicitly.
Blockstudio\Pages::force_sync_all();

// Reconcile a complete deployment inventory without rewriting equal pages.
$report = Blockstudio\Pages::reconcile([
  'authoritative' => true,
  'plan_valid' => true,
  'source' => [
    'commit' => $commit,
    'dirtyHash' => $dirtyHash,
  ],
]);

// Store this only after the matching static artifact and routes verify.
Blockstudio\Pages::store_successful_source_identity($report['sourceIdentity']);

// Lock a page against non-authoritative reconciliation.
Blockstudio\Pages::lock('about');

// Unlock a page.
Blockstudio\Pages::unlock('about');

// Register a page renderer (inside the blockstudio/pages/renderers action).
Blockstudio\Page_Renderers::register('react', [
  'extensions' => ['tsx'],
  'layouts' => ['layout.tsx'],
  'render' => 'my_theme_render_page',
]);

// Find the renderer of an entry file.
$renderer = Blockstudio\Page_Renderers::for_entry('page.tsx');

// Register assets for rendered output and print the returned marker with it.
$marker = Blockstudio\Assets::register_owner('page-home', [$scriptPath]);

인수 의미, 보고서 필드, 확인된 소스 ID 경계는 배포 조정을 참조하세요.

템플릿과 레이아웃에서 사용할 수 있는 전역 헬퍼 함수:

PHP
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();

Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children() 및 전역 헬퍼가 반환하는 페이지 배열에는 동기화된 글 ID, 소스 및 템플릿 경로, 컬렉션/경로 메타데이터, 콘텐츠 유형, 동기화 정책, 글 유형/상태, 편집 정책, 사용자 지정 메타데이터, permalink 키가 포함됩니다. 컬렉션 메타데이터는 마지막으로 성공한 명시적 조정에서 불러옵니다. 일반 요청에서는 페이지 소스 트리를 읽지 않고 저장된 구성과 동기화된 글 메타데이터에서 이 런타임 데이터를 재구성합니다. Pages 클래스에는 별도의 퍼머링크 메서드가 없습니다.

파일 기반 페이지 만들기

템플릿 잠금, 블록 편집 모드, 키 기반 병합, 클라이언트가 편집할 수 있는 항목 제어.