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

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

## 파일 기반 컬렉션

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

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

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

[페이지 컬렉션](https://blockstudio.dev/ko/docs/pages-and-patterns/pages/#page-collections)

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 블록으로 분석합니다.

[페이지 구문 참고 자료](https://blockstudio.dev/ko/docs/pages-and-patterns/pages/)

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 자체는 컴포넌트 페이지로 구성됩니다.

[컴포넌트 페이지](https://blockstudio.dev/ko/docs/pages-and-patterns/pages/#component-pages)

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()` 는 사이트맵에 해당 경로를 반환합니다.

[가상 경로](https://blockstudio.dev/ko/docs/pages-and-patterns/pages/#virtual-routes)

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()` 를 호출해 기계가 읽을 수 있는 보고서를 받습니다.

[동기화 동작](https://blockstudio.dev/ko/docs/pages-and-patterns/pages/#sync-behavior)

터미널

```
# 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` 를 추가하세요. 다음 동기화 때 키가 지정된 블록은 템플릿 속성을 기존 사용자 콘텐츠와 병합하고, 키가 없는 블록은 대체됩니다.

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

[키가 있는 블록](https://blockstudio.dev/ko/docs/pages-and-patterns/pages/#keyed-block-merging)

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` 로 요소를 재정의하면 잠긴 페이지를 선택적으로 편집할 수 있으며 개별 블록을 비활성화할 수 있습니다.

[템플릿 잠금](https://blockstudio.dev/ko/docs/pages-and-patterns/pages/#template-lock)

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` 소스가 제공됩니다.

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

[사이트 템플릿](https://blockstudio.dev/ko/docs/pages-and-patterns/site-templates/)

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는 메타데이터를 옮기고 페이지 동기화는 본문을 유지합니다.

[콘텐츠 동기화](https://blockstudio.dev/ko/docs/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 커뮤니티

[Plus 이용하기](https://blockstudio.dev/ko/plus/)
