theme.json을 사용하여 커스텀 WordPress 블록 테마를 만드는 방법: 단계별 가이드

요약

Full Site Editing(FSE)을 사용한 커스텀 WordPress 블록 테마 제작은 어려울 수 있지만, theme.json이 과정을 단순화합니다. 이 가이드는 최소 블록 테마 설정, theme.json에서 색상 및 타이포그래피와 같은 글로벌 스타일 정의, 블록 마크업을 사용한 커스텀 템플릿 생성 과정을 안내합니다. 블록 패턴과 스타일 변형을 추가하여 PHP 템플릿 파일 없이도 완전히 디자인 가능한 사이트를 만들 수 있습니다. 클래식 테마와 블록 테마 기능을 혼합하는 것과 같은 일반적인 실수를 다루고 테스트 방법을 보여줍니다. 마지막에는 프로덕션에 바로 사용 가능한 현대적이고 확장 가능한 블록 테마를 갖추게 됩니다. 이 접근 방식은 WordPress의 최신 기능을 활용하여 더 빠르고 시각적인 개발을 가능하게 합니다.

소개

Full Site Editing(FSE)은 WordPress 테마 개발에 혁신을 가져와 사이트의 모든 부분을 시각적으로 디자인할 수 있게 했습니다. 그러나 많은 개발자가 여전히 클래식 테마에 의존하거나 처음부터 블록 테마를 만드는 데 어려움을 겪고 있습니다. FSE의 힘을 활용하는 열쇠는 theme.json – 글로벌 스타일, 설정 및 템플릿을 제어하는 구성 파일입니다. 이 기사는 theme.json을 사용한 커스텀 블록 테마 제작에 대한 실용적인 단계별 가이드를 제공합니다. 폴더 구조 설정, 색상 팔레트 및 타이포그래피 프리셋 정의, 블록 마크업을 사용한 커스텀 템플릿 생성, 스타일 변형 추가 방법을 배우게 됩니다. 마지막에는 유지 관리 및 확장이 쉬운 프로덕션 준비 블록 테마를 갖추게 됩니다. FSE 개발을 이해하기 쉽게 만들어 보겠습니다.

FSE가 WordPress 디자인의 미래를 어떻게 형성하고 있는지 더 폭넓게 알아보려면 Gutenberg FSE: 2026년 WordPress 디자인의 미래를 확인하세요.

1. 최소 블록 테마 설정

블록 테마는 최소한 두 개의 파일(style.css 및 index.html)이 필요합니다. 이 파일들을 만들어 보겠습니다.

폴더 구조

wp-content/themes/ 디렉토리에 my-block-theme 폴더를 만듭니다. 안에 다음 파일을 배치합니다:

• style.css
• index.html
• (선택 사항) theme.json

style.css

블록 테마는 CSS에 덜 의존하지만, style.css는 테마 식별을 위해 여전히 필요합니다:

/*
Theme Name: My Block Theme
Theme URI: https://example.com
Author: Your Name
Description: A custom block theme built with theme.json.
Version: 1.0
Requires at least: 5.9
Tested up to: 6.5
Requires PHP: 7.4
License: GPL v2 or later
Text Domain: my-block-theme
*/

Requires at least: 5.9 줄은 테마가 FSE 기능과 함께 작동하도록 보장합니다.

index.html

이것은 대체 템플릿입니다. 블록 마크업으로 시작해야 합니다. 간단한 레이아웃을 만듭니다:

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
    <!-- wp:post-title /-->
    <!-- wp:post-content /-->
</div>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

이것은 블록 문법을 사용하여 헤더 및 푸터 템플릿 부분을 포함하고, 게시물 제목과 콘텐츠를 표시합니다.

주의: 블록 테마는 header.php 또는 footer.php와 같은 PHP 템플릿 파일을 포함해서는 안 됩니다. 클래식 템플릿과 블록 템플릿을 혼합하면 FSE가 손상됩니다.

테마 활성화

FTP를 통해 폴더를 업로드하거나 zip 설치 후 활성화합니다. 최소 구조의 빈 사이트가 표시되어야 합니다. 다음으로 theme.json으로 스타일을 지정합니다.

2. theme.json 마스터하기: 글로벌 스타일 및 설정

theme.json은 모든 디자인 컨트롤을 중앙집중화합니다. 테마 폴더의 루트에 위치합니다. 색상 및 타이포그래피 설정과 함께 하나를 만들어 보겠습니다.

기본 구조

{
    "version": 2,
    "settings": {
        "color": {
            "palette": [
                {
                    "slug": "primary",
                    "color": "#007cba",
                    "name": "Primary"
                },
                {
                    "slug": "secondary",
                    "color": "#005a87",
                    "name": "Secondary"
                },
                {
                    "slug": "background",
                    "color": "#ffffff",
                    "name": "Background"
                }
            ],
            "gradients": []
        },
        "typography": {
            "fontFamilies": [
                {
                    "fontFamily": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
                    "slug": "system",
                    "name": "System"
                },
                {
                    "fontFamily": "'Georgia', serif",
                    "slug": "serif",
                    "name": "Serif"
                }
            ],
            "fontSizes": [
                {
                    "slug": "small",
                    "size": "14px",
                    "name": "Small"
                },
                {
                    "slug": "medium",
                    "size": "18px",
                    "name": "Medium"
                },
                {
                    "slug": "large",
                    "size": "24px",
                    "name": "Large"
                }
            ]
        },
        "spacing": {
            "padding": true,
            "margin": true,
            "units": ["px", "em", "rem"]
        }
    },
    "styles": {
        "color": {
            "background": "var(--wp--preset--color--background)",
            "text": "var(--wp--preset--color--primary)"
        },
        "typography": {
            "fontFamily": "var(--wp--preset--font-family--system)",
            "fontSize": "var(--wp--preset--font-size--medium)"
        }
    }
}

이것은 색상 팔레트, 글꼴 패밀리, 글꼴 크기 및 글로벌 스타일을 정의합니다. var() 함수는 WordPress가 자동으로 생성하는 CSS 사용자 정의 속성을 참조합니다. 사용자는 사이트 편집기에서 이를 변경할 수 있습니다.

팁: 일관성을 위해 CSS 사용자 정의 속성을 사용하세요. CSS 파일에 값을 하드코딩하지 말고 theme.json을 단일 진실 공급원으로 삼으세요.

3. 커스텀 템플릿 만들기

블록 템플릿은 블록 마크업이 있는 HTML 파일입니다. 클래식 템플릿 파일과 유사한 계층 구조를 따릅니다. 예를 들어, 단일 게시물을 위한 single.html을 만듭니다:

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
    <!-- wp:post-title {"level":1} /-->
    <!-- wp:post-featured-image /-->
    <!-- wp:post-content /-->
    <!-- wp:post-navigation-link {"type":"previous"} /-->
    <!-- wp:post-navigation-link {"type":"next"} /-->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

마찬가지로 page.html, archive.html 등을 만듭니다. 쿼리 루프 내에 wp:post-template 블록을 추가하여 커스텀 템플릿을 만들 수도 있습니다.

고급 사용자 정의는 커스텀 블록 구축을 고려하세요. 기본 블록을 넘어서: 향상된 WordPress 기능을 위한 커스텀 Gutenberg 블록 제작에서 자세히 알아보세요.

템플릿 부분

재사용 가능한 부분을 위해 parts/ 폴더를 만듭니다. 예를 들어 header.html:

<!-- wp:group {"tagName":"header","layout":{"type":"flex","flexWrap":"nowrap"}} -->
<header class="wp-block-group">
    <!-- wp:site-logo /-->
    <!-- wp:navigation {"themeLocation":"primary"} /-->
</header>
<!-- /wp:group -->

그리고 footer.html:

<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center">&copy; 2025 My Site</p>
<!-- /wp:paragraph -->

4. 블록 패턴 및 스타일 변형 추가

블록 패턴은 미리 디자인된 레이아웃입니다. patterns/ 폴더에 정의하세요. patterns/hero.php를 만듭니다:

<?php
/**
 * Title: Hero
 * Slug: my-block-theme/hero
 * Categories: hero
 */
?>
<!-- wp:cover {"overlayColor":"primary","minHeight":50,"align":"full"} -->
<div class="wp-block-cover alignfull" style="min-height:50vh">
    <span aria-hidden="true" class="wp-block-cover__background has-primary-background-color"></span>
    <div class="wp-block-cover__inner-container">
        <!-- wp:heading {"textAlign":"center","level":1,"style":{"color":{"text":"#ffffff"}}} -->
        <h1 class="has-text-align-center has-text-color" style="color:#ffffff">환영합니다</h1>
        <!-- /wp:heading -->
        <!-- wp:paragraph {"align":"center","textColor":"white"} -->
        <p class="has-text-align-center has-white-color">이것은 사용자 정의 히어로 섹션입니다</p>
        <!-- /wp:paragraph -->
    </div>
</div>
<!-- /wp:cover -->

스타일 변형을 통해 사용자는 전체 룩을 전환할 수 있습니다. styles/default.json과 styles/dark.json을 만들어 테마 설정을 재정의하세요.

5. 주의사항 및 모범 사례

• 성능: theme.json은 캐시됩니다. 변경 후 캐시를 지우세요. 필요한 경우 wp_register_theme_json 훅을 사용하세요.
• 하위 호환성: 블록 테마는 WordPress 5.9 이상에서만 작동합니다. 사이트가 이전 버전을 지원해야 하는 경우 하이브리드 접근 방식을 고려하되 템플릿 파일을 혼합하지 마세요.
• 자식 테마: 블록 테마는 클래식 자식 테마의 부모 테마로 사용될 수 있지만 그 반대는 불가능합니다. style.css에서 template을 사용하여 부모 블록 테마를 선언하세요.
• 국제화: 번역 가능한 문자열에 대해 PHP 템플릿 부분 내에서 __() 함수를 사용하세요. 블록 마크업에서는 textDomain 속성을 통해 텍스트 도메인을 지정하세요.

플러그인 개발 모범 사례에 대한 자세한 내용은 강력한 WordPress 플러그인 구축: 모범 사례에 대한 실용 가이드를 참조하세요.

결론

theme.json을 사용한 커스텀 블록 테마 구축은 PHP를 건드리지 않고도 완전히 디자인 가능한 사이트를 만들 수 있게 해줍니다. 이 가이드를 따라 최소 테마 설정, 글로벌 스타일 정의, 커스텀 템플릿 생성, 패턴 추가를 완료했습니다. 특히 아카이브 페이지나 사용자 정의 게시물 유형과 같은 엣지 케이스를 철저히 테스트하세요. WordPress가 발전함에 따라 블록 테마가 표준이 될 것입니다. 지금 FSE를 활용하여 워크플로우를 간소화하고 클라이언트에게 비교할 수 없는 유연성을 제공하세요.

테마 생성을 더욱 가속화하려면 설명에서 완전한 사이트를 생성하는 도구를 사용하는 것을 고려하세요. 예를 들어, 원하는 레이아웃을 설명하면 몇 분 안에 사용 가능한 블록 테마를 얻을 수 있습니다.

블록 테마를 라이브로 전환할 준비가 되셨나요? 일반 텍스트 설명만으로 완전한 기능의 랜딩 페이지나 웹사이트를 생성할 수 있습니다. 코딩이 필요하지 않습니다.