* 이 게시물은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.
(워드프레스 해부 ⑮) 템플릿
쿼리가 “단일 글”이라고 정하면, 워드프레스는 그걸 그릴 템플릿 파일을 찾는다. 이때 따르는 규칙이 템플릿 계층(template hierarchy)이다. 핵심 원리는 하나 — 구체적인 것부터 찾다가, 없으면 일반적인 것으로 폴백한다.
예를 들어 “뉴스” 카테고리 페이지라면 이 순서로 파일을 찾는다.
category-news.php(그 카테고리 전용) →category-5.php(카테고리 ID) →category.php(모든 카테고리) →archive.php(모든 보관함) →index.php(최후의 보루 — 이건 무조건 있어야 한다)
단일 글이면 single-{post_type}.php → single.php → index.php, 페이지면 page-{slug}.php → page.php → index.php 식이다. 규칙만 알면 “이 화면을 커스텀하려면 어떤 파일을 만들면 되나”가 바로 나온다. 블록 테마는 파일 대신 templates/ 폴더의 .html이 같은 계층을 따른다.
직접 해보기
어떤 템플릿이 실제로 쓰였는지는 6편에서 깐 Query Monitor가 바로 보여준다. 관리자 바 → Query Monitor → Template 패널을 열면 현재 페이지가 어떤 템플릿 파일로 그려졌는지, 어떤 후보들을 거쳤는지 나온다.
# body 태그의 클래스에도 힌트가 있다 (템플릿 종류를 반영)
# 페이지 소스에서 <body class="..."> 확인:
# category / archive / single / page-id-13 ...
# 이 클래스로 CSS를 페이지 종류별로 다르게 줄 수도 있다✅ 확인 — 카테고리 페이지에서 Query Monitor의 Template 패널을 열어, 후보 목록이
category.php → archive.php → index.php순으로 나열되고 실제 선택된 게 표시되는지 확인하자. 이게 계층 폴백을 눈으로 보는 방법이다.
전체 계층을 큰 갈래로
화면 유형마다 순서는 다르지만 원리는 하나다 — 구체적인 파일부터 찾고, 없으면 일반적인 것으로 폴백한다. 그리고 모든 경로는 결국 index.php로 수렴한다. 그래서 테마는 index.php 하나만 있어도 일단 동작한다. 자주 만나는 화면의 탐색 순서를 정리하면 이렇다.
| 보는 화면 | 찾는 순서 (구체 → 일반) |
|---|---|
| 단일 글 | single-{타입}-{슬러그} → single-{타입} → single → singular → index |
| 고정 페이지 | page-{슬러그} → page-{id} → page → singular → index |
| 카테고리 | category-{슬러그} → category-{id} → category → archive → index |
| 태그 | tag-{슬러그} → tag → archive → index |
| 홈(글 목록) | home → index |
| 검색 / 404 | search / 404 → index |
어떤 템플릿이 선택됐는지 확인하기
추측하지 말고 확인한다. Query Monitor(32편)의 ‘Template’ 패널은 지금 어떤 파일이 선택됐고 어떤 후보들이 있었는지를 순서대로 보여준다. 코드로 직접 찍어보고 싶으면 template_include 필터가 가장 확실하다.
add_filter( 'template_include', function ( $template ) {
if ( WP_DEBUG ) error_log( '선택된 템플릿: ' . $template );
return $template; // 반드시 그대로 반환
} );블록 테마(FSE)에선 파일 형식만 다르다
위는 클래식 테마(PHP 파일) 기준이다. 블록 테마에선 templates/ 폴더의 HTML 파일이 같은 이름 규칙을 따른다 — single.html, archive.html처럼. 파일 형식이 PHP에서 HTML로 바뀔 뿐, ‘구체→일반 폴백’이라는 계층 개념은 그대로다. 그래서 계층을 한 번 이해해두면 두 방식 모두에 쓰인다.
전용 템플릿을 만들고 싶을 때
커스텀 포스트 타입(24편)은 single-{타입}.php로 전용 화면을 준다. 특정 고정 페이지만 다르게 하려면 page-{슬러그}.php를 두거나, 파일 상단에 주석을 달아 편집 화면에서 고를 수 있는 ‘페이지 템플릿’으로 만든다.
<?php /* Template Name: 넓은 레이아웃 */ ?>
<!-- 이 파일을 두면 페이지 편집 화면의 '템플릿'에서 고를 수 있다 -->계층은 결국 ‘워드프레스가 화면마다 어떤 파일을 고르는가’의 지도다. 이 지도를 손에 쥐면 테마를 뜯어보거나 만들 때 헤매지 않는다.
화면을 그리는 파일을 골랐으니, 다음 편은 그 화면에 CSS·JS를 올바르게 불러오는 법(엔큐)이다. 그냥 <link> 넣으면 왜 안 되는지.
자주 묻는 질문 (FAQ)
워드프레스는 어떤 템플릿 파일을 고르나요?
요청 종류(단일글·카테고리·검색 등)에 따라 정해진 우선순위로 찾습니다. single.php·category.php처럼 구체적인 게 우선입니다.
어떤 템플릿이 선택됐는지 알 수 있나요?
Query Monitor나 template_include 훅으로 실제 선택된 템플릿 파일을 확인할 수 있습니다.
답글 남기기