본문으로 건너뛰기
레퍼런스

WordPress 블록 테마 템플릿 계층 구조

블록 테마(FSE)의 전체 템플릿 계층 구조: 모든 요청 유형에 대해 WordPress가 찾는 템플릿을 가장 구체적인 것부터 순서대로 나열하며, 마지막에는 index.html로 대체합니다. 클래식 계층 구조 도표의 블록 시대 버전입니다.

각 요청마다 WordPress는 이 템플릿들을 순서대로 — 가장 구체적인 것부터 — 찾아본 뒤, 테마의 /templates 폴더에 존재하는 첫 번째 템플릿에서 멈춥니다. 이 연쇄는 항상 index.html에서 끝납니다.

사이트 첫 페이지

최신 글 목록으로 설정했든 정적 페이지로 설정했든, 사이트의 첫 페이지입니다.

  1. front-page.html
  2. home.html
  3. index.html

설정 → 읽기 선택과 관계없이 front-page.html이 우선합니다. 첫 페이지가 정적 페이지이면서 front-page.html이 없으면 home.html이 아니라 정적 페이지 체인으로 넘어갑니다.

블로그 글 목록

최신 글을 나열하는 페이지입니다(설정 → 읽기의 "글 페이지").

  1. home.html
  2. index.html

개별 글

하나의 블로그 글입니다.

  1. single-post-{slug}.html
  2. single-post.html
  3. single.html
  4. singular.html
  5. index.html

개별 사용자 정의 글 유형

사용자 정의 글 유형(예: "book")의 개별 항목입니다.

  1. single-{post-type}-{slug}.html
  2. single-{post-type}.html
  3. single.html
  4. singular.html
  5. index.html

슬러그가 "dune"인 "book" 글 유형의 경우: single-book-dune.html, 다음 single-book.html, 그다음 single.html 순입니다.

정적 페이지

일반적인 WordPress 페이지입니다.

  1. page-{slug}.html
  2. page-{id}.html
  3. page.html
  4. singular.html
  5. index.html

사용자 정의 템플릿을 지정한 페이지

편집기의 템플릿 패널에서 사용자 정의 템플릿을 지정한 페이지입니다.

  1. {custom-template}.html
  2. page-{slug}.html
  3. page-{id}.html
  4. page.html
  5. singular.html
  6. index.html

사용자 정의 템플릿은 theme.json의 customTemplates 배열에 선언되며 /templates에 위치합니다. 지정된 템플릿이 페이지 체인 전체보다 우선합니다.

카테고리 아카이브

한 카테고리에 속한 글을 나열하는 아카이브입니다.

  1. category-{slug}.html
  2. category-{id}.html
  3. category.html
  4. archive.html
  5. index.html

태그 아카이브

한 태그가 붙은 글을 나열하는 아카이브입니다.

  1. tag-{slug}.html
  2. tag-{id}.html
  3. tag.html
  4. archive.html
  5. index.html

사용자 정의 분류 아카이브

사용자 정의 분류의 특정 용어에 대한 아카이브입니다.

  1. taxonomy-{taxonomy}-{term}.html
  2. taxonomy-{taxonomy}.html
  3. taxonomy.html
  4. archive.html
  5. index.html

작성자 아카이브

한 작성자의 글을 모은 아카이브입니다.

  1. author-{nicename}.html
  2. author-{id}.html
  3. author.html
  4. archive.html
  5. index.html

날짜 아카이브

연도 / 월 / 일 단위 아카이브입니다.

  1. date.html
  2. archive.html
  3. index.html

글 유형 아카이브

has_archive가 설정된 사용자 정의 글 유형의 아카이브 목록입니다.

  1. archive-{post-type}.html
  2. archive.html
  3. index.html

검색 결과

사이트 검색의 결과 페이지입니다.

  1. search.html
  2. index.html

404 (찾을 수 없음)

URL과 일치하는 콘텐츠가 없을 때 표시됩니다.

  1. 404.html
  2. index.html

첨부 파일 페이지

단일 미디어 첨부 파일을 위한 페이지입니다.

  1. attachment.html
  2. single.html
  3. singular.html
  4. index.html

많은 사이트가 첨부 파일 페이지를 아예 비활성화합니다(내용이 빈약하기 때문입니다). 유지하는 경우 이것이 그 체인입니다.

개인정보처리방침 페이지

설정에서 사이트의 개인정보처리방침으로 지정한 페이지입니다.

  1. page-privacy-policy.html
  2. privacy-policy.html
  3. page.html
  4. singular.html
  5. index.html

기존 (PHP) 계층 구조와 어떻게 다른가

  • 템플릿은 테마 루트의 .php 파일이 아니라 /templates 안의 .html 파일입니다. single.php는 없으며, single.html입니다.
  • 재사용 가능한 영역(헤더, 푸터)은 get_header() / get_footer() PHP 호출이 아니라 /parts에 있는 템플릿 파트이며, wp:template-part 블록으로 참조합니다.
  • get_template_part() 체인도 없고 get_header()/get_footer()도 없습니다. 구성은 .html 파일 안의 템플릿 파트 블록으로 이루어집니다.
  • index.html은 필수입니다. templates/index.html이 없는 block theme는 유효한 block theme가 아닙니다. 이는 위의 모든 경로에 대한 필수 최종 대체 수단입니다.
  • 테마가 block theme로 인식되는 것은 어떤 헤더 플래그가 아니라 templates/index.html과 theme.json의 존재 여부로 결정됩니다.
  • 이 템플릿들은 사이트 편집기(외모 → 편집기)에서 편집하여 데이터베이스에 저장할 수 있으며, 저장된 변경 사항은 사용자 정의를 지울 때까지 테마 파일보다 우선 적용됩니다. "왜 내 템플릿 변경이 아무 효과가 없지"를 디버깅하는 사람들이 여기서 당황하곤 합니다.