정적 HTML 사이트를 워드프레스 커스텀 테마로 이전하기 ④ 서브페이지를 관리자에서 수정 가능하게 만들기

지난 글에서는 정적 HTML의 헤더·푸터를 워드프레스 테마 파일로 분리하고, 메뉴와 자주 변경되는 정보를 관리자에서 수정할 수 있도록 연결했다.

이번에는 여러 개의 서브페이지를 어떤 방식으로 워드프레스에 넣을지 결정하고, 실제 페이지 하나를 관리자에서 수정 가능한 구조로 옮겼다.

처음에는 페이지별 PHP 템플릿을 만들려고 했지만, 운영과 SEO까지 생각해 구조를 다시 변경했다.

처음 생각한 페이지별 PHP 방식

워드프레스는 페이지 슬러그에 맞춰 다음과 같은 템플릿 파일을 사용할 수 있다.

/about/      → page-about.php
/service/    → page-service.php
/contact/    → page-contact.php

정적 HTML의 본문을 각 PHP 파일로 옮기면 원본 디자인을 안정적으로 유지할 수 있다.

처음에는 다음과 같이 페이지별 파일을 만들 계획이었다.

custom-theme/
├── page-about.php
├── page-service.php
├── page-contact.php
├── page-about.css
├── page-service.css
└── page-contact.css

하지만 첫 번째 서브페이지를 변환하면서 이 구조가 실제 운영에는 불편하다는 점을 발견했다.

페이지 안의 문구나 이미지 하나를 수정할 때마다 FTP에 접속해 PHP 파일을 수정해야 하기 때문이다.

페이지별 PHP 방식의 문제점

페이지 내용을 PHP 파일에 직접 작성하면 워드프레스 관리자에서 해당 페이지를 열었을 때 본문이 비어 있다.

이 방식에는 다음과 같은 단점이 있었다.

문구 수정에도 FTP 접속이 필요하다.
관리자가 워드프레스에서 내용을 수정할 수 없다.
워드프레스의 수정 이력 기능을 활용하기 어렵다.
페이지 내용이 데이터베이스의 본문에 저장되지 않는다.
SEO 플러그인이 페이지 내용을 분석하기 어려울 수 있다.
페이지가 많아지면 PHP와 CSS 파일도 계속 늘어난다.
다른 작업자가 구조를 이해하고 관리하기 어렵다.

디자인을 그대로 복원하는 것만 생각하면 페이지별 PHP 방식도 가능하지만, 사이트를 장기간 운영하는 구조로는 적합하지 않다고 판단했다.

관리자에 모든 코드를 넣는 방식도 문제였다

그렇다고 HTML, CSS, JavaScript를 모두 워드프레스 페이지 편집기에 넣는 것도 좋은 방법은 아니었다.

페이지마다 CSS까지 넣으면 다음과 같은 문제가 생긴다.

공통 CSS가 여러 페이지에 중복된다.
전체 디자인을 수정하려면 모든 페이지를 열어야 한다.
코드가 너무 길어져 내용을 찾기 어렵다.
<style>이나 <script>가 저장 과정에서 변경될 수 있다.
공통 링크와 이미지 경로를 한 번에 관리하기 어렵다.

결국 PHP 파일 방식과 관리자 입력 방식 중 하나를 선택하는 것이 아니라, 각각의 장점을 나눠 사용하는 구조가 필요했다.

최종적으로 선택한 구조

최종 구조는 다음과 같다.

내용	관리 위치
헤더·푸터	테마 PHP 파일
공통 페이지 출력	`page.php`
공통·페이지별 디자인	`subpages.css`
페이지 본문 HTML	워드프레스 관리자
메뉴	워드프레스 메뉴
연락처·외부 링크	사이트 설정
SEO 제목·설명·스키마	SEO 플러그인

페이지마다 PHP 파일을 만들지 않고, 모든 일반 페이지가 함께 사용하는 page.php 하나만 만들었다.

공통 page.php 만들기

page.php는 워드프레스 관리자의 페이지 본문을 출력하는 역할만 담당한다.

<?php get_header(); ?>

<?php
while (have_posts()) :
    the_post();
    the_content();
endwhile;
?>

<?php get_footer(); ?>

이제 워드프레스에서 생성한 일반 페이지는 모두 이 파일을 사용한다.

페이지 관리자가 입력한 본문 앞뒤에는 테마의 공통 헤더와 푸터가 자동으로 붙는다.

header.php
    ↓
관리자에서 입력한 페이지 HTML
    ↓
footer.php

이 구조에서는 새로운 서브페이지를 만들 때마다 PHP 파일을 추가할 필요가 없다.

서브페이지 CSS 통합하기

원본 HTML에는 각 페이지의 <head> 안에 페이지 전용 CSS가 포함돼 있었다.

이 CSS를 페이지 관리자에 같이 넣지 않고, 모두 추출해 subpages.css 하나로 합쳤다.

custom-theme/
├── page.php
├── subpages.css
├── functions.php
├── header.php
└── footer.php

여러 페이지의 CSS를 비교해보니 페이지 개수보다 실제 디자인 유형은 훨씬 적었다.

같은 레이아웃을 사용하는 페이지는 동일한 CSS를 공유하고 있었기 때문에 완전히 같은 CSS는 중복으로 넣지 않았다.

functions.php에서는 일반 페이지일 때 subpages.css를 불러오도록 설정했다.

if (is_front_page()) {
    // 메인 페이지 CSS
} elseif (is_page()) {
    wp_enqueue_style(
        'custom-theme-subpages',
        $theme_uri . '/subpages.css',
        ['custom-theme-style'],
        filemtime($theme_dir . '/subpages.css')
    );

    $base_dependencies = ['custom-theme-subpages'];
}

메인 페이지도 워드프레스의 페이지이므로 is_page() 조건보다 is_front_page()를 먼저 확인해야 한다.

그렇지 않으면 메인 페이지에서도 서브페이지 CSS가 적용될 수 있다.

관리자에 페이지 HTML 넣기

워드프레스에서 페이지를 생성한 다음 본문에는 일반 문단 블록이 아닌 사용자 정의 HTML 블록을 사용했다.

진행 순서는 다음과 같다.

관리자에서 페이지 → 새 페이지 추가로 이동
페이지 제목 입력
기존 URL과 같은 슬러그 설정
본문에 사용자 정의 HTML 블록 추가
변환한 페이지 HTML 붙여넣기
공개 또는 업데이트
실제 URL에서 결과 확인

관리자에 붙여넣는 코드에는 다음 내용만 포함했다.

<main id="main">
    <!-- 페이지 제목 영역 -->
    <!-- 페이지별 본문 -->
    <!-- 관련 링크 및 버튼 -->
</main>

다음 내용은 넣지 않았다.

<!DOCTYPE html>
<html>
<head>
<body>
header
footer
SEO 메타태그
canonical
JSON-LD
noindex

헤더와 푸터는 테마에서 출력하고, SEO 관련 정보는 나중에 SEO 플러그인으로 관리하기 때문이다.

특히 원본 HTML에 개발용 noindex가 들어 있다면 그대로 복사하지 않도록 주의해야 한다.

이미지가 표시되지 않았던 문제

처음 변환한 페이지에는 이미지 주소를 다음처럼 작성했다.

<img src="[custom_theme_uri]/_astro/example.webp" alt="">

[custom_theme_uri]를 실제 테마 주소로 변환해 사이트가 다른 도메인으로 이동하더라도 이미지 경로가 유지되도록 만들려는 목적이었다.

하지만 사용자 정의 HTML 블록의 src와 srcset 안에서는 이 값이 예상대로 변환되지 않았다.

결과적으로 브라우저가 다음 문자열을 이미지 주소로 인식하면서 이미지가 표시되지 않았다.

[custom_theme_uri]/_astro/example.webp

콘텐츠 출력 전에 주소 변환하기

페이지마다 이미지 주소를 직접 고치는 대신, the_content 필터를 사용해 페이지가 출력되기 전에 주소를 변환하도록 수정했다.

function custom_theme_replace_content_tokens($content) {
    return str_replace(
        [
            '[custom_theme_uri]',
            '[custom_theme_home]',
        ],
        [
            esc_url(get_template_directory_uri()),
            esc_url(home_url()),
        ],
        $content
    );
}

add_filter(
    'the_content',
    'custom_theme_replace_content_tokens',
    8
);

이제 관리자에 다음과 같이 입력해도:

<img src="[custom_theme_uri]/_astro/example.webp" alt="예시 이미지">

<a href="[custom_theme_home]/about/">소개 페이지</a>

실제 화면에서는 다음과 같은 주소로 변환된다.

<img src="https://사이트주소/wp-content/themes/custom-theme/_astro/example.webp">

<a href="https://사이트주소/about/">소개 페이지</a>

도메인이나 워드프레스 설치 경로가 바뀌어도 관리자에 입력한 모든 이미지 주소를 다시 수정할 필요가 없다.

수정된 functions.php를 업로드하고 강력 새로고침한 뒤 이미지가 정상적으로 출력되는 것을 확인했다.

공통 버튼은 숏코드로 연결하기

전화, 예약, 지도 같은 버튼을 페이지 HTML마다 고정으로 작성하면 주소가 바뀌었을 때 모든 페이지를 수정해야 한다.

이를 방지하기 위해 버튼 영역은 다음과 같은 공통 숏코드로 교체했다.

[custom_theme_cta_group heading_id="page-cta-heading"]

이 숏코드는 관리자 사이트 설정에 저장된 정보를 불러와 버튼을 출력한다.

전화 연결
외부 예약
길찾기
버튼 이름
버튼 표시 여부

이제 연락처나 외부 링크가 바뀌면 각 페이지의 HTML을 수정할 필요 없이 사이트 설정에서 한 번만 수정하면 된다.

관리자에서 수정할 수 있는 범위

이번 구조에서는 다음 항목을 관리자에서 직접 수정할 수 있다.

페이지 제목과 본문
소개 문구
목록과 카드 내용
이미지 대체텍스트
내부 링크 이름과 연결 주소
HTML 요소의 추가와 삭제
페이지 슬러그
메뉴 이름과 순서
연락처와 외부 링크

다음 항목은 테마 파일에서 관리한다.

공통 헤더와 푸터
색상과 간격
반응형 디자인
페이지 레이아웃 CSS
공통 JavaScript
숏코드 기능

문구나 내용 변경은 관리자에서 처리하고, 디자인이나 기능 변경이 필요할 때만 FTP를 사용하도록 역할을 나눴다.

이 구조가 SEO와 AEO에 유리한 이유

페이지 내용을 PHP 템플릿에 고정하지 않고 워드프레스 본문에 저장하면 다음 작업이 편해진다.

SEO 플러그인의 콘텐츠 분석
페이지별 SEO 제목과 설명 설정
내부 링크 확인
이미지 대체텍스트 관리
워드프레스 검색 기능 활용
페이지 수정 이력 확인
FAQ와 구조화 데이터 연결
사이트 이전 및 데이터 내보내기

SEO 제목, 메타 설명, canonical, Open Graph, 스키마는 본문 HTML에 직접 작성하지 않고 SEO 플러그인에서 관리할 예정이다.

앞으로의 서브페이지 작업 방식

공통 페이지 구조와 CSS가 완성됐기 때문에 다음부터는 반복 작업이다.

페이지별 작업 순서는 다음과 같다.

원본 HTML에서 <main> 영역 추출
헤더·푸터·SEO 코드 제거
이미지 주소를 테마 경로 토큰으로 변경
내부 링크를 사이트 주소 토큰으로 변경
공통 버튼을 숏코드로 교체
워드프레스에서 페이지 생성
기존 주소와 같은 슬러그 입력
사용자 정의 HTML 블록에 코드 붙여넣기
페이지 공개
PC와 모바일 화면 확인
메뉴와 내부 링크 연결

새로운 페이지를 만들 때마다 별도의 page-{slug}.php 파일을 추가할 필요는 없다.

페이지의 HTML은 관리자에서 관리하고, 모든 서브페이지의 디자인은 공통 subpages.css를 사용한다.

작업 결과

이번 단계에서 완료한 내용은 다음과 같다.

페이지별 PHP 템플릿 방식 재검토
공통 page.php 제작
서브페이지 CSS 통합
중복 CSS 제거
사용자 정의 HTML 블록을 이용한 페이지 본문 관리
이미지 테마 경로 자동 변환
내부 링크 주소 자동 변환
공통 버튼 숏코드 연결
관리자에서 페이지 내용 수정 가능
첫 서브페이지 PC 화면 출력 확인

처음에는 정적 HTML을 PHP 파일로 옮기는 것만 생각했지만, 실제 운영 방식을 고려하면서 구조를 수정했다.

정적 HTML의 디자인은 유지하면서도 워드프레스 관리 기능을 활용하려면 모든 코드를 한곳에 넣기보다 역할을 적절히 나누는 것이 중요했다.

다음 단계에서는 같은 방식으로 나머지 서브페이지를 생성하고, 페이지별 HTML을 관리자에 입력할 예정이다. 모든 페이지 이전이 끝나면 메뉴, 내부 링크, 반응형 화면을 점검한 뒤 SEO와 AEO 설정을 진행한다.