첫 프로젝트 전까지는 안다고 생각했던 WordPress 테마 개발

AI 요약

HTML, CSS, PHP와 기본적인 WordPress 관리 화면을 다룰 줄 알았던 글쓴이는 첫 실무 프로젝트에서 테마 개발의 어려움이 코드 작성 자체에 있지 않다는 사실을 알게 됩니다. 튜토리얼에서는 디자인을 HTML, CSS, PHP로 옮기면 끝나는 것처럼 보이지만, 실제 작업에서는 WordPress의 구조, 템플릿 선택 방식, 콘텐츠, hooks, 에디터 동작, 프런트엔드 테스트를 함께 고려해야 합니다.

■ 테마는 시각적 레이어만이 아닙니다

처음에는 작업 흐름을 ‘디자인 → HTML → CSS → PHP → WordPress’로 생각했습니다. 실제 흐름은 ‘디자인 → WordPress 구조 → 템플릿 → 콘텐츠 → hooks → 스타일 → 에디터 동작 → 프런트엔드 테스트’에 더 가깝습니다. 테마가 콘텐츠를 보여주기는 하지만, 어떤 방식으로 조립하고 표시할지는 WordPress가 결정합니다.

그래서 특정 페이지를 디자인과 똑같이 만들려고 파일을 억지로 수정하기보다, 해당 페이지 유형을 WordPress가 어떤 방식으로 구성하도록 설계했는지 먼저 묻는 편이 낫다고 설명합니다. 이 관점의 변화가 레이아웃 문제를 무작정 수정하는 대신 시스템의 동작을 확인하는 출발점이 됐습니다.

■ 클래식 테마와 블록 테마를 먼저 구분합니다

작업을 시작하기 전에 어떤 종류의 테마를 만들지 정해야 합니다. 클래식 테마는 주로 PHP 템플릿, JavaScript, CSS에 의존합니다. 블록 테마는 블록, 템플릿, template parts, patterns, theme.json을 중심으로 구성합니다.

현대적인 블록 테마에서는 style.css, theme.json, templates, template parts, patterns, functions.php가 서로 다른 책임을 맡습니다. 기본 블록 테마에 필요한 파일은 style.css와 templates/index.html입니다. 글쓴이는 CSS부터 작성하지 않고 다음 질문을 먼저 확인하는 방식으로 작업 순서를 바꿨습니다.

• 블록 테마와 클래식 테마 중 어느 쪽이 필요한가요?
• 실제로 필요한 템플릿은 무엇인가요?
• 어떤 영역을 재사용 가능한 template part로 만들까요?
• theme.json에 어떤 설정을 둘까요?
• 테마 밖에서도 유지해야 하는 기능은 무엇인가요?

초기에 구조를 정하면 나중에 엉킨 파일을 다시 정리하는 일을 줄일 수 있습니다.

■ 템플릿 계층을 이해하면 디버깅 방식이 달라집니다

WordPress의 template hierarchy는 요청에 가장 잘 맞는 템플릿을 찾는 규칙입니다. 개별 페이지, 글, 아카이브, 작성자 화면 등에 더 구체적인 템플릿이 있으면 그것을 사용하고, 일치하는 템플릿이 없으면 계층을 따라가며 적절한 대체 템플릿을 찾습니다.

이 규칙을 알기 전에는 페이지가 잘못 보일 때 파일을 무작정 고쳤습니다. 이후에는 “WordPress가 실제로 어떤 템플릿을 사용하고 있나?”를 먼저 확인했습니다. 글쓴이는 개별 파일 이름을 외우는 것보다 계층의 작동 원리를 이해하는 편이 custom theme 개발에 더 도움이 된다고 말합니다. 원리를 알면 파일 이름도 자연스럽게 연결됩니다.

■ functions.php와 플러그인의 경계를 나눕니다

처음에는 동작한다는 이유로 custom functions, scripts, styles, hooks와 작은 기능을 모두 functions.php에 넣었습니다. 파일이 커지면서 유지보수가 어려워졌습니다.

functions.php는 테마 기능 추가, 테마 기능 등록, hooks 사용, asset 로딩, 재사용 함수 정의에 사용할 수 있습니다. 다만 활성 테마가 바뀌어도 남아 있어야 하는 기능은 플러그인에 두는 편이 낫습니다. 글쓴이가 정리한 기준은 간단합니다. 사이트의 외형을 바꾸는 기능은 테마에 두고, 테마를 바꿔도 사이트가 계속 제공해야 하는 기능은 플러그인을 고려합니다.

이 기준은 절대적인 규칙은 아니지만 시작점으로 유용합니다. 예를 들어 custom post type처럼 콘텐츠 자체가 테마 변경 뒤에도 남아야 하는 기능은 플러그인에 두는 방식이 적절하다고 설명합니다.

■ 블록과 theme.json으로 디자인 결정을 관리합니다

블록 테마에서는 PHP 템플릿과 CSS를 계속 추가하는 대신 블록 마크업으로 템플릿을 구성할 수 있습니다. Site Editor에서 템플릿과 template parts를 시각적으로 다룰 수도 있습니다. 헤더, 푸터, 페이지 레이아웃, 재사용 영역을 만들 때 모든 경우를 하드코딩하기보다 다른 관리자가 유지보수할 방식을 함께 고려해야 합니다.

theme.json은 typography, color, spacing, layout과 에디터 관련 설정을 관리합니다. 같은 시각 규칙을 CSS에 반복해서 작성하는 대신 글꼴, 간격, 색상, 레이아웃 제약, 블록 설정, 재사용 가능한 디자인 값을 체계적으로 정의할 수 있습니다. 글쓴이가 느낀 장점은 CSS를 단순히 덜 작성하는 데 있지 않습니다. 테마의 동작과 디자인 결정을 더 예측하기 쉬워진다는 점입니다.

■ 에디터 화면만 보고 테마를 끝내지 않습니다

WordPress 에디터에서 제대로 보이는 레이아웃이 실제 사이트에서 다르게 동작하는 문제가 첫 프로젝트에서 발생했습니다. 이후 주요 컴포넌트를 다음 조건으로 확인했습니다.

• 에디터에서 어떻게 보이는가요?
• 프런트엔드에서는 어떻게 보이는가요?
• 모바일에서 어떻게 동작하나요?
• 실제 콘텐츠를 넣으면 어떻게 되나요?
• 콘텐츠가 예상보다 길어지면 어떻게 되나요?
• 다른 편집자가 레이아웃을 깨뜨리지 않고 수정할 수 있나요?

디자인 파일은 한 가지 상태만 보여줍니다. 실제 사이트에서는 제목이 두 배로 길어질 수 있고, 글에 대표 이미지가 없을 수도 있습니다. 클라이언트가 메뉴 항목을 세 개가 아니라 다섯 개 넣을 수도 있으며, 큰 이미지를 붙여넣거나 짧은 문단과 긴 버튼 레이블을 사용할 수도 있습니다. 샘플 콘텐츠에서만 완벽한 템플릿은 실제 콘텐츠를 만나면 쉽게 무너집니다.

따라서 글쓴이는 한 장의 스크린샷이 아니라 콘텐츠의 변형을 기준으로 테마를 만들고, 이상적인 입력뿐 아니라 일부러 까다로운 콘텐츠도 초기에 넣어 봅니다. 테마가 완성됐다고 판단하는 기준도 개발자가 원하는 화면을 만들었는지가 아닙니다. 사이트 운영자가 개발자에게 계속 도움을 요청하지 않고 관리할 수 있는지가 기준입니다.

■ 첫 프로젝트를 다시 한다면

다시 시작한다면 먼저 요구사항을 파악하고 클래식 테마와 블록 테마 중 필요한 방식을 정합니다. 그다음 스타일링에 많은 시간을 쓰기 전에 테마 구조를 세웁니다. 템플릿과 재사용 영역을 매핑하고, 전역 디자인 결정을 일찍 정의합니다. 테마에만 필요한 기능과 테마 변경 뒤에도 남아야 하는 기능을 분리한 뒤, 모든 컴포넌트를 따로 끝내기보다 완성된 페이지 하나를 먼저 만듭니다. 마지막으로 실제 콘텐츠와 의도적으로 까다로운 콘텐츠를 넣어 테스트합니다.

개발 중에는 WordPress Theme Developer Handbook을 열어 두는 것도 권합니다. 핸드북은 클래식 테마와 블록 테마의 구조, 템플릿, functions.php, assets, theme.json, patterns와 고급 주제를 다룹니다. 글쓴이가 얻은 결론은 WordPress의 모든 함수와 파일 이름을 외우는 데 있지 않습니다. 튜토리얼과 다르게 동작하는 순간에도 WordPress가 기대하는 구조를 이해하고 적절한 결정을 내리는 데 있습니다.

■ dev.to 반응

• @mayur-upadhyay — “페이지를 디자인과 똑같이 맞추려면 어떻게 해야 하지?”에서 “WordPress는 이 페이지를 어떻게 만들도록 요구하지?”로 관점을 바꾸는 법을 더 일찍 배웠으면 했습니다. 코드를 건드리기 전에 WordPress가 실제로 어떤 템플릿을 사용하는지 묻는 것만으로도 시간을 많이 아낍니다. 스크린샷을 기준으로 만드는 부분도 특히 인상 깊었습니다. 디자인은 완벽한 한 순간만 보여주지만 실제 사이트에는 긴 제목, 없는 대표 이미지, 메뉴 항목을 더 추가하는 클라이언트가 있습니다. 어색한 콘텐츠로 일찍 테스트하면 막판 수정이 많이 줄어듭니다. functions.php와 플러그인을 나누는 경험칙도 좋았습니다. 단순하고, 많은 사람이 한 번쯤 만든 ‘모든 것을 한 파일에 넣기’ 문제를 막아줍니다. 경험을 공유해주셔서 감사합니다!
  • @elsie-rainee — 정말 감사합니다. 템플릿에 관한 질문이 제 디버깅 방식을 바꿨습니다. 추측을 멈추고 WordPress가 어떤 템플릿을 로드하는지만 확인했더니, 해결되지 않던 레이아웃 문제의 절반은 단순한 문제로 드러났습니다. 첫 프로젝트에서는 스크린샷을 기준으로 만든 일이 가장 큰 교훈이었습니다. 클라이언트가 실제 콘텐츠를 추가하기 전까지 디자인은 완벽해 보였고, 콘텐츠가 들어오자 모든 것이 깨졌습니다. 이제는 첫날부터 어색한 콘텐츠로 테스트합니다. functions.php에 관한 규칙도 유용했다니 다행입니다. 테마를 옮긴 뒤 플러그인에 있어야 했던 기능을 잃어버리고 나서야 배웠습니다. 본인의 프로젝트에서도 비슷하게 예상하지 못한 문제가 있었나요? 무엇이 가장 당황스러웠는지 듣고 싶습니다.
• @sidra-jefferi — 공감되는 글입니다. 대부분의 튜토리얼은 테마 개발을 디자인에서 HTML, CSS, PHP로 이어지는 직선처럼 보여주지만, 실제 프로젝트는 더 복잡합니다. 템플릿 계층을 먼저 배워야 한다는 지적이 정확합니다. 코드를 건드리기 전에 “WordPress가 실제로 어떤 템플릿을 사용하고 있지?”라고 묻는 것만으로도 무작위 디버깅을 많이 줄일 수 있습니다. 에디터와 프런트엔드를 따로 테스트하는 부분도 좋았습니다. 에디터에서 완벽해 보이는 레이아웃이 실제 사이트에서는 깨질 수 있고, 인수인계 뒤 다른 사람이 개발자를 부르지 않고 관리할 수 있어야 한다는 목표를 많은 개발자가 놓칩니다. 블록 테마로 넘어가는 사람에게 반복해서 CSS를 작성하는 대신 theme.json으로 디자인 결정을 예측 가능하게 만드는 방법도 좋은 팁입니다. 경험을 공유해주셔서 감사합니다!
  • @elsie-rainee — 감사합니다. “WordPress가 실제로 어떤 템플릿을 사용하고 있지?”라고 묻는 것이 제 디버깅 방식을 완전히 바꿨습니다. 인수인계에 관한 말씀도 맞습니다. 다른 사람이 개발자에게 연락하지 않고 관리할 수 있어야 테마가 완성됐다고 느낍니다. theme.json에 관한 팁도 유용하게 봐주셔서 감사합니다!
• @rafidbottler — 좋은 글입니다, Elsie. functions.php 부분을 읽고 궁금해졌습니다. 클라이언트가 custom post type 같은 것을 요청하면 테마 코드와 플러그인의 경계를 어디에 두나요? 팀마다 다르게 처리하는 모습을 봤고, 보통 나중에 테마를 바꿀 때 문제가 드러났습니다. block theme과 theme.json으로 완전히 옮겨갔는지도 궁금합니다. 아니면 일부 프로젝트에서는 여전히 classic theme을 사용하나요?
  • @elsie-rainee — 읽어주셔서 감사합니다. custom post type은 거의 언제나 플러그인에 둡니다. 디자인이 바뀐 뒤에도 콘텐츠가 남아 있어야 한다면 테마에 들어갈 기능이 아니기 때문입니다. 가장 자주 본 실패는 클라이언트가 테마를 바꾼 뒤 portfolio나 team 페이지가 관리자 화면에서 갑자기 사라지는 경우입니다. 테마에는 template parts, styles, 레이아웃에 종속된 hooks처럼 표현을 담당하는 기능을 둡니다. block theme은 이제 대부분의 새 프로젝트에서 사용합니다. 주로 theme.json이 디자인 결정을 예측 가능한 한곳에 모아주기 때문입니다. 기존 PHP 템플릿이 많거나 클라이언트 팀이 이미 classic theme 유지보수에 익숙한 프로젝트에서는 여전히 classic theme을 사용합니다. 단지 최신 방식이라는 이유로 잘 작동하는 classic theme을 다시 만드는 일은 대체로 이득이 없습니다. 어느 방식이 더 새로운지보다 누가 사이트를 유지보수할지에 따라 선택합니다.

원문: dev.to / 번역·요약: Trawling