문서 사이트 만들기
문서는 설명하는 코드 가까이에 있어야 합니다. 작성자는 Markdown을 선호하고 검토자는 풀 리퀘스트에서 변경 사항을 확인하고 싶어 하며, 릴리스에는 동일한 커밋의 문서가 포함되어야 합니다. 반면 WordPress에는 데이터베이스에 게시물이 필요합니다. 검색, 고유 주소, 수정 기록, 편집기가 모두 그곳에 있기 때문입니다.
Blockstudio 페이지 컬렉션은 이 둘을 연결합니다. Markdown 파일이 폴더에 모여 실제 WordPress 게시물 세트가 되며, 자체 게시물 유형과 URL 기본 경로, 상위 및 하위 계층을 갖습니다. layout.php 파일은 같은 데이터로 만든 탐색 메뉴를 사용해 컬렉션의 모든 페이지를 감쌉니다. 파일이 원본 데이터로 유지되며 명시적 동기화 명령을 통해 데이터베이스에 기록됩니다.
이 가이드는 acme이라는 테마를 위한 작은 문서 섹션을 단계별로 만듭니다. 매니페스트, Markdown 페이지, 변경 기록을 생성하는 로더, 동기화, 사이드바와 이전 및 다음 링크가 있는 레이아웃을 다룹니다.
만들 항목
theme/
└── pages/
└── docs/
├── pages.json
├── layout.php
├── loader.php
├── index.md
├── getting-started.md
├── data/
│ └── releases.json
└── guide/
├── index.md
├── install.md
└── configure.md
동기화 후 컬렉션에서 다음 URL을 제공합니다:
| 소스 | 공개 URL |
|---|---|
index.md |
/docs/ |
getting-started.md |
/docs/getting-started/ |
guide/index.md |
/docs/guide/ |
guide/install.md |
/docs/guide/install/ |
guide/configure.md |
/docs/guide/configure/ |
| 로더 항목 | /docs/changelog/ |
1단계: 컬렉션 매니페스트
컬렉션은 pages/ 안에 있는 폴더로, pages.json 매니페스트를 포함합니다. pages/docs/pages.json를 만드세요:
{
"collection": "docs",
"title": "Documentation",
"postType": "acme_docs",
"postTypeArgs": {
"label": "Docs"
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
collection는 컬렉션 슬러그이며 공개 URL 기본 경로가 됩니다. postType는 컬렉션의 모든 페이지를 전용 게시물 유형에 넣으므로 문서가 관리자 화면의 일반 페이지와 섞이지 않습니다. 해당 게시물 유형이 아직 없으면 Blockstudio가 등록합니다. 등록 기본값은 공개, 계층형이며 REST API에서 사용할 수 있고, 제목, 편집기, 페이지 속성, 썸네일, 요약 및 수정 기록을 지원합니다. 다시 쓰기 슬러그는 컬렉션 슬러그와 같습니다. postTypeArgs는 이러한 기본값에 병합되므로 이 매니페스트는 관리자 레이블만 변경합니다.
defaults는 컬렉션의 모든 페이지에 페이지 속성을 적용합니다. 여기서는 동기화할 때 모든 페이지를 게시하고 콘텐츠 전용 편집으로 잠그므로 편집자는 편집기에서 오타를 고칠 수 있지만 Markdown가 정의한 구조를 재배치할 수 없습니다.
2단계: Markdown로 페이지 작성
컬렉션 안에서는 모든 Markdown 파일이 페이지입니다. 파일 위치가 페이지의 식별자이므로 프런트매터는 선택 사항입니다. 프런트매터를 사용해 제목, 정렬 순서, 나중에 읽을 추가 데이터를 지정하세요.
---
title: Introduction
order: 0
description: What Acme does and where to start.
---
# Introduction
Acme is a toolkit for building fast WordPress sites.
Start with [Getting Started](/docs/getting-started/).
---
title: Getting Started
order: 10
---
# Getting Started
Install the theme, then activate it under **Appearance > Themes**.
```bash
wp theme activate acme
```
가이드 섹션은 자체 index.md가 있는 폴더이며, 이 폴더는 옆에 있는 페이지의 상위 항목이 됩니다:
---
title: Guide
order: 20
---
# Guide
Task-focused walkthroughs for everyday work.
---
title: Installation
order: 10
---
# Installation
| Requirement | Version |
| --- | --- |
| WordPress | 6.7+ |
| PHP | 8.2+ |
---
title: Configuration
order: 20
---
# Configuration
Settings live in `acme.json` at the theme root.
> Changes apply on the next deploy.
Blockstudio는 각 파일에서 논리 경로와 페이지 이름을 추출합니다:
| 파일 | 경로 | 페이지 이름 |
|---|---|---|
index.md |
. |
docs-home |
getting-started.md |
getting-started |
docs-getting-started |
guide/index.md |
guide |
docs-guide |
guide/install.md |
guide/install |
docs-guide-install |
guide/install.md와 guide/install/index.md는 같은 경로를 생성하므로 나중에 파일 형식과 폴더 형식 간에 전환해도 URL는 바뀌지 않습니다.
order는 형제 페이지를 정렬하며 게시물의 메뉴 순서로 기록됩니다. 순서가 지정되지 않은 페이지는 순서가 지정된 페이지 뒤에 오고 제목순으로 정렬됩니다. Blockstudio가 인식하지 못하는 프런트매터 키(위의 description 등)는 페이지의 meta 배열에 보존됩니다.
동기화 중 Markdown는 GitHub Flavored Markdown로 파싱되고 HTML로 변환된 다음 네이티브 블록으로 파싱됩니다. 저장된 게시물에는 블록이 포함되며 Markdown 텍스트는 포함되지 않습니다. 제목에는 안정적인 앵커가 지정되고 표는 core/table가 되며 인용문은 core/quote가 되고 코드 펜스는 언어 클래스를 보존하는 core/preformatted 블록이 됩니다. 다음은 설치 페이지의 저장된 콘텐츠입니다(공백 제거):
<!-- wp:heading {"level":1,"anchor":"installation"} --><h1 id="installation" class="wp-block-heading">Installation</h1><!-- /wp:heading -->
<!-- wp:table --><figure class="wp-block-table"><table>
<thead><tr><th>Requirement</th><th>Version</th></tr></thead>
...
</table></figure><!-- /wp:table -->
3단계: 로더로 페이지 생성
일부 페이지는 직접 작성하는 것보다 생성하는 편이 낫습니다. 변경 기록이 좋은 예입니다. 릴리스 데이터가 이미 있는데 이를 Markdown에 직접 복사하면 내용이 어긋나기 쉽습니다. 컬렉션에는 추가 페이지 정의를 반환하는 loader.php를 포함할 수 있습니다.
릴리스 데이터는 컬렉션에 보관하세요:
[
{ "version": "1.1.0", "date": "2026-09-01", "notes": "Added dark mode." },
{ "version": "1.0.0", "date": "2026-06-15", "notes": "First release." }
]
그런 다음 데이터에서 Markdown 페이지 하나를 만드세요:
<?php
$releases = json_decode(
(string) file_get_contents( __DIR__ . '/data/releases.json' ),
true
);
$markdown = "# Changelog\n";
foreach ( $releases as $release ) {
$markdown .= "\n## {$release['version']}\n\n";
$markdown .= "Released {$release['date']}. {$release['notes']}\n";
}
return array(
'pages' => array(
array(
'name' => 'docs-changelog',
'title' => 'Changelog',
'path' => 'changelog',
'order' => 90,
'content' => $markdown,
'contentType' => 'markdown',
),
),
);
로더는 명시적인 검색 및 동기화 중에 실행되며 일반 페이지 보기 중에는 실행되지 않습니다. 결정적이고 로컬에서 동작하도록 유지하세요. 테마의 파일을 읽는 것은 괜찮지만 원격 API를 가져오는 것은 피해야 합니다. 그러면 동기화가 해당 서비스의 연결 가능 여부에 좌우되기 때문입니다.
로더 페이지는 생성된 페이지로 표시됩니다. 로더 출력에서 항목이 사라지면 다음 동기화는 해당 게시물을 고아로 처리하고 blockstudio/pages/orphan_action 필터를 통해 처리합니다. 기본적으로 휴지통으로 이동합니다.
로더는 다른 로컬 Markdown 폴더를 컬렉션에 연결하기 위해 선택적으로 접두사를 지정하여 paths를 반환할 수도 있습니다. 컬렉션 루트 밖에 있는 폴더에는 blockstudio/pages/allow_external_loader_path 필터가 필요합니다. 전체 구조는 컬렉션 로더를 참조하세요.
4단계: 동기화
요청하기 전까지 데이터베이스에는 아무것도 기록되지 않습니다:
wp bs pages sync
이 명령은 모든 페이지 소스를 검색하고 acme_docs 게시물 유형을 등록한 다음 게시물을 생성하거나 업데이트합니다. 이어서 discovered, created, updated, unchanged, removed, failed 개수를 포함한 요약 행을 출력합니다. 변경 없이 다시 실행하면 모든 페이지가 변경되지 않은 것으로 표시되며 게시물은 기록되지 않습니다. 배포 스크립트에서 전체 보고서가 필요하면 --format=json을 추가하세요.
동기화가 끝나면 게시물은 파일 트리를 반영합니다. guide/install은 컬렉션 루트의 하위 항목인 guide의 하위 항목이며, 각 게시물의 메뉴 순서는 프런트매터의 order입니다. 컬렉션 URL은 컬렉션 슬러그와 각 페이지의 논리적 경로를 결합합니다:
/docs/
/docs/getting-started/
/docs/guide/
/docs/guide/install/
/docs/guide/configure/
/docs/changelog/
고유 주소를 다시 저장할 필요는 없습니다. 등록된 컬렉션 게시물 유형이 변경되면 컬렉션 다시 쓰기 규칙이 자동으로 플러시됩니다.
배포 과정에 동기화를 포함하세요. 프런트엔드 및 관리자 요청은 페이지 검색을 실행하지 않으므로 새 Markdown 파일을 복사하면서 wp bs pages sync를 실행하지 않으면 이전 콘텐츠가 계속 제공됩니다.
5단계: 레이아웃
이제 게시물이 있지만 각각 테마의 일반 단일 템플릿으로 렌더링되며 탐색 기능도 없습니다. layout.php 옆에 있는 pages.json는 컬렉션의 모든 페이지를 프런트엔드에서 렌더링할 때 감싸는 역할을 합니다:
<?php
$current = blockstudio_current_page();
$tree = blockstudio_page_tree( 'docs' );
// Flatten the tree in reading order for previous and next links.
$flat = array();
$flatten = function ( array $nodes ) use ( &$flatten, &$flat ) {
foreach ( $nodes as $node ) {
$flat[] = $node;
$flatten( $node['children'] );
}
};
$flatten( $tree );
$keys = array_column( $flat, 'key' );
$position = array_search( $current['key'] ?? null, $keys, true );
$previous = false !== $position ? ( $flat[ $position - 1 ] ?? null ) : null;
$next = false !== $position ? ( $flat[ $position + 1 ] ?? null ) : null;
$render_nav = function ( array $nodes ) use ( &$render_nav, $current ) {
echo '<ul>';
foreach ( $nodes as $node ) {
$is_current = ( $node['key'] ?? null ) === ( $current['key'] ?? null );
printf(
'<li><a href="%s"%s>%s</a>',
esc_url( $node['permalink'] ?? '#' ),
$is_current ? ' aria-current="page"' : '',
esc_html( $node['title'] )
);
if ( array() !== $node['children'] ) {
$render_nav( $node['children'] );
}
echo '</li>';
}
echo '</ul>';
};
?>
<div class="docs">
<nav class="docs-sidebar" aria-label="Documentation">
<?php $render_nav( $tree ); ?>
</nav>
<article class="docs-content">
<?php echo blockstudio_page_content(); ?>
<nav class="docs-pager" aria-label="Previous and next">
<?php if ( $previous ) : ?>
<a rel="prev" href="<?php echo esc_url( $previous['permalink'] ?? '#' ); ?>">
<?php echo esc_html( $previous['title'] ); ?>
</a>
<?php endif; ?>
<?php if ( $next ) : ?>
<a rel="next" href="<?php echo esc_url( $next['permalink'] ?? '#' ); ?>">
<?php echo esc_html( $next['title'] ); ?>
</a>
<?php endif; ?>
</nav>
</article>
</div>
blockstudio_page_tree('docs')는 컬렉션을 중첩 노드로 반환하며 order, 제목순으로 정렬하고 각 노드의 하위 항목은 children에 담습니다. 여기에는 루트가 하나 있는데, 소개 페이지 아래에 다른 페이지가 배치됩니다. 각 노드에는 key, title, path, permalink가 포함됩니다. 트리를 이 순서로 평탄화하면 이전 및 다음 링크에 필요한 읽기 순서가 만들어집니다.
blockstudio_page_content()은 WordPress가 the_content를 통해 렌더링할 페이지 본문을 출력합니다. 이를 생략하면 콘텐츠가 숨겨집니다. https://example.com에 있는 사이트의 /docs/guide/install/에서는 레이아웃이 다음과 같이 렌더링됩니다(일부 생략):
<nav class="docs-sidebar" aria-label="Documentation">
<ul><li><a href="https://example.com/docs/">Introduction</a><ul>
<li><a href="https://example.com/docs/getting-started/">Getting Started</a></li>
<li><a href="https://example.com/docs/guide/">Guide</a><ul>
<li><a href="https://example.com/docs/guide/install/" aria-current="page">Installation</a></li>
<li><a href="https://example.com/docs/guide/configure/">Configuration</a></li>
</ul></li>
<li><a href="https://example.com/docs/changelog/">Changelog</a></li>
</ul></li></ul>
</nav>
...
<a rel="prev" href="https://example.com/docs/guide/">Guide</a>
<a rel="next" href="https://example.com/docs/guide/configure/">Configuration</a>
레이아웃은 기본 루프의 단일 프런트엔드 요청에서만 실행됩니다. 저장된 post_content를 변경하지 않으며 편집기 캔버스도 감싸지 않습니다. 경로는 동기화된 각 게시물에 저장되며 페이지 지문의 일부이므로 레이아웃을 수정하면 다음 동기화에서 반영됩니다.
PHP에서 컬렉션 데이터 읽기
레이아웃 헬퍼는 Blockstudio\Pages 클래스의 얇은 래퍼입니다. 템플릿, 블록 또는 플러그인에서 다음 형식 중 하나를 사용하세요:
| 헬퍼 | 클래스 메서드 | 반환값 |
|---|---|---|
blockstudio_pages('docs') |
Pages::pages('docs') |
페이지 키를 기준으로 정렬한 컬렉션 페이지의 평탄화된 목록 |
blockstudio_page_tree('docs') |
Pages::tree('docs') |
children가 포함된 중첩 노드 |
blockstudio_page_children('docs-guide', 'docs') |
Pages::children('docs-guide', 'docs') |
한 페이지의 직계 하위 페이지 |
blockstudio_page_collection('docs') |
Pages::collection('docs') |
매니페스트의 컬렉션 데이터 |
blockstudio_current_page() |
Pages::current_page() |
렌더링 중인 페이지 또는 null |
Pages::get_page('docs-guide-install') |
이름으로 찾은 페이지 하나 |
페이지 배열에는 동기화된 post_id, permalink, name, key, title,
path, order, collection, postType 및 meta 배열이 포함됩니다. Frontmatter의
추가 항목은 meta에 저장되므로 레이아웃에서 서론의 요약을 출력할 수 있습니다:
<?php $summary = $current['meta']['description'] ?? ''; ?>
프런트엔드 요청에서 이 함수들은 이미 동기화된 게시물과 마지막 동기화 때 저장된 설정을 읽습니다. Markdown 파일은 읽지 않으므로 파일 시스템 작업이 필요하지 않습니다. 프런트엔드에서는 게시된 페이지만 사용할 수 있습니다.
도구용 원시 Markdown
페이지는 Markdown 파일에서 가져오므로 Blockstudio에서 원본 소스도 제공할 수 있습니다.
.md 접미사가 붙은 페이지를 요청하세요. 예: /docs/guide/install.md. 또는 일반 URL에
Accept: text/markdown를 전송하세요. 응답에는 frontmatter가 포함되지 않으며, 정식 Link 헤더로
HTML 페이지를 가리킵니다. 이는 검색 색인 도구, 어시스턴트 및 일반 텍스트를
읽는 다른 도구에 유용합니다. 인라인 로더 콘텐츠에서 생성된 페이지에는 소스 파일이
없으므로 .md 응답도 제공되지 않습니다.
필터 하나로 끄세요:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
팁
경로에 구조를 담으세요. 파일을 옮기면 경로, 상위 항목, URL도 다음 동기화 때
함께 변경됩니다. 파일 위치와 URL가 달라야 할 때만 frontmatter의 path를 사용하세요.
페이지에 더 많은 정보가 필요하면 page.json와 Markdown를 함께 사용하세요.
page.json 및 index.md가 있는 폴더에서는 페이지 속성(예: postId 또는 templateLock)에
JSON를, 콘텐츠에는 Markdown를 사용합니다. index.md의 frontmatter 값은 일치하는
page.json 값을 우선합니다.
편집기가 아니라 파일에서 작성하세요. templateLock: "contentOnly"를 사용하면 편집기에서 텍스트를
직접 수정할 수 있지만, 변경된 소스를 다음에 동기화하면 파일 내용으로 저장된 콘텐츠를
덮어씁니다. 문서를 작성하는 곳은 Markdown로 삼으세요. 편집자가 소유해야 하는 페이지는
page.json의 "sync": false를 지정하면 일반 동기화에서 건너뛰고, Blockstudio\Pages::force_sync()가 한 번 생성합니다.
게시물 유형을 바꿔도 안전합니다. 컬렉션을 page에서 사용자 지정 게시물 유형으로
옮기면 저장된 식별자가 일치하는 기존 동기화 게시물이 제자리에서 마이그레이션되므로
게시물 ID가 유지됩니다.
다음 단계
- 페이지 참조: 모든
page.json및pages.json속성, 로더, 레이아웃, 조정 보고서. - 파일 기반 페이지 만들기: 템플릿 잠금, 블록 편집 모드, 클라이언트가 편집하는 페이지의 키 기반 병합.
- 사이트 편집기 템플릿 및 파일 기반 부분 템플릿: 헤더, 푸터, 테마 템플릿에 적용하는 동일한 파일 우선 방식.