워드프레스 특정 페이지에 커스텀 템플릿 적용하는 방법: page-slug.php 사용법

워드프레스 페이지 템플릿이란?

페이지 템플릿은 워드프레스 페이지가 화면에 표시되는 구조를 결정하는 파일입니다. 같은 페이지라도 어떤 템플릿을 사용하느냐에 따라 제목 위치, 본문 너비, 사이드바, 이미지 영역과 버튼 배치가 달라질 수 있습니다.

PHP 기반 테마에서 자주 사용하는 템플릿 파일은 다음과 같습니다.

예를 들어 일반 페이지는 `page.php`를 사용하면서 문의 페이지에만 `page-contact.php`를 적용하면 페이지별로 서로 다른 디자인을 사용할 수 있습니다.

`page-contact.php`는 파일 이름 자체가 적용 대상을 지정하므로 별도의 `Template Name` 주석이나 관리자 화면의 템플릿 선택 과정이 필요하지 않습니다.

page-slug.php 작동 원리

슬러그는 페이지 URL을 식별하는 문자열이며, 일반적으로 URL의 마지막 경로 구성요소로 표시됩니다.

다음 주소를 예로 들어보겠습니다.

https://example.com/contact/

이 페이지의 슬러그는 다음과 같습니다.

contact

따라서 전용 템플릿 파일 이름은 다음과 같이 작성합니다.

page-contact.php

다른 페이지도 같은 방식으로 설정할 수 있습니다.

슬러그와 파일 이름은 정확히 일치해야 합니다. 페이지 슬러그가 `contact-us`라면 `page-contact.php`가 아니라 `page-contact-us.php`를 만들어야 합니다.

워드프레스 공식 문서에서는 `page-{slug}.php`를 특정 페이지에 적용되는 전용 템플릿으로 안내합니다.

참고: WordPress 공식 문서: Page Templates

페이지 생성과 슬러그 확인

먼저 워드프레스 관리자에서 실제 페이지를 생성해야 합니다. 템플릿 파일만 만들어서는 새로운 페이지 주소가 자동으로 생성되지 않습니다.

다음 순서로 페이지를 만듭니다.

① 워드프레스 관리자에 로그인합니다. ② `페이지 → 새 페이지 추가`로 이동합니다. ③ 페이지 제목을 입력합니다. ④ 페이지의 URL 또는 슬러그를 확인합니다. ⑤ 페이지를 게시합니다.

문의 페이지를 만든다면 다음과 같이 설정할 수 있습니다.

페이지 제목: 문의하기
페이지 슬러그: contact
페이지 주소: https://example.com/contact/

페이지 제목과 별도로 URL 슬러그를 확인하거나 수정할 수 있습니다.

페이지 게시 후 `/contact/` 주소에 접속해 페이지가 공개되어 있는지 확인합니다. 실제로 적용된 템플릿은 이후 단계에서 별도로 확인합니다.

차일드 테마에 템플릿 파일 만들기

템플릿 파일은 현재 활성화된 테마 폴더에 추가해야 합니다. 기존 테마를 사용하는 경우에는 부모 테마보다 차일드 테마에 파일을 추가하는 편이 안전합니다.

부모 테마를 직접 수정하면 테마 업데이트 과정에서 변경 사항이 사라질 수 있기 때문입니다.

차일드 테마의 기본 경로는 다음과 같습니다.

/wp-content/themes/your-child-theme/

문의 페이지의 전용 템플릿을 만들려면 다음 파일을 추가합니다.

/wp-content/themes/your-child-theme/page-contact.php

차일드 테마 폴더 이름이 `mytheme-child`라면 실제 파일 경로는 다음과 같습니다.

/wp-content/themes/mytheme-child/page-contact.php

`page-{slug}.php` 형식의 파일은 테마 루트에 두는 것이 기본입니다.

올바른 위치:

/wp-content/themes/mytheme-child/page-contact.php

다음처럼 임의의 하위 폴더에 저장하면 슬러그 전용 템플릿으로 자동 적용되지 않을 수 있습니다.

잘못된 위치:

/wp-content/themes/mytheme-child/templates/page-contact.php

서버 파일을 수정하는 방법으로 SSH 연결을 사용할 수 있습니다. 설치와 연결 절차는 VS Code를 cPanel 서버에 SSH로 연결하는 방법에서 확인할 수 있습니다.

기본 PHP 템플릿 코드 작성

`page-contact.php` 파일을 생성했다면 다음 코드를 추가합니다.

<?php
/**
 * 문의 페이지 전용 템플릿입니다.
 *
 * 페이지 슬러그가 contact인 경우
 * page-contact.php 파일이 자동으로 적용됩니다.
 */

// 현재 사용 중인 테마의 헤더를 불러옵니다.
get_header();
?>

<main id="primary" class="site-main contact-page">
    <?php
    // 표시할 페이지 데이터가 있는 동안 실행합니다.
    while ( have_posts() ) :

        // 현재 페이지의 제목과 본문을 사용할 수 있도록 준비합니다.
        the_post();
        ?>

        <section class="contact-page__content">
            <div class="container">
                <h1>
                    <?php
                    // 현재 페이지 제목을 HTML에 안전하게 출력합니다.
                    echo esc_html( get_the_title() );
                    ?>
                </h1>

                <div class="contact-page__body">
                    <?php
                    // 워드프레스 편집기에 작성한 본문을 출력합니다.
                    the_content();
                    ?>
                </div>
            </div>
        </section>

        <?php
    // 페이지 데이터 출력 과정을 종료합니다.
    endwhile;
    ?>
</main>

<?php
// 현재 사용 중인 테마의 푸터를 불러옵니다.
get_footer();
?>

각 함수의 역할은 다음과 같습니다.

이 코드를 적용하면 기존 사이트의 헤더와 푸터를 유지하면서 문의 페이지에만 다른 HTML 구조를 적용할 수 있습니다.

또한 `the_content()`가 포함되어 있으므로 페이지 편집기에서 작성한 문구, 이미지와 블록이 함께 표시됩니다. 문의 양식은 본문에 블록이나 숏코드로 삽입한 경우 플러그인 방식에 따라 이 출력 영역에 표시될 수 있습니다.

원하는 HTML 레이아웃 추가하기

기본 템플릿이 정상적으로 표시된다면 필요한 디자인 요소를 직접 추가할 수 있습니다.

다음 예시는 페이지 상단에 소개 영역을 만들고, 아래쪽에 문의 안내와 페이지 본문을 나란히 배치하는 구조입니다.

<?php
/**
 * 문의 페이지 전용 커스텀 템플릿입니다.
 */

// 사이트의 공통 헤더를 불러옵니다.
get_header();
?>

<main id="primary" class="site-main contact-page">
    <?php
    // 현재 페이지 데이터를 불러옵니다.
    while ( have_posts() ) :

        // 페이지 제목과 본문을 사용할 수 있도록 설정합니다.
        the_post();
        ?>

        <!-- 페이지 상단 소개 영역입니다. -->
        <section class="contact-hero">
            <div class="container">
                <!-- 페이지의 보조 제목입니다. -->
                <p class="contact-hero__label">
                    Contact
                </p>

                <!-- 관리자 화면에 입력한 페이지 제목을 출력합니다. -->
                <h1 class="contact-hero__title">
                    <?php echo esc_html( get_the_title() ); ?>
                </h1>

                <!-- 템플릿에 직접 작성한 고정 안내 문구입니다. -->
                <p class="contact-hero__description">
                    문의 내용을 남겨주시면 확인 후 연락드리겠습니다.
                </p>
            </div>
        </section>

        <!-- 문의 안내와 페이지 본문을 표시하는 영역입니다. -->
        <section class="contact-details">
            <div class="container">
                <div class="contact-details__grid">
                    <!-- 왼쪽: 문의 안내와 서비스 소개 링크입니다. -->
                    <div class="contact-details__information">
                        <h2>문의 안내</h2>

                        <p>
                            서비스 이용, 웹사이트 제작 및 기타 문의 사항을
                            편하게 남겨주세요.
                        </p>

                        <!-- /services/는 실제 사이트의 서비스 페이지 경로로 바꿔 사용합니다. -->
                        <a
                            class="contact-details__button"
                            href="<?php echo esc_url( home_url( '/services/' ) ); ?>"
                        >
                            서비스 안내 보기
                        </a>
                    </div>

                    <!-- 오른쪽: 관리자에서 작성한 페이지 본문입니다. -->
                    <div class="contact-details__content">
                        <?php
                        // 편집기에 작성한 본문, 블록 또는 문의 양식을 출력합니다.
                        the_content();
                        ?>
                    </div>
                </div>
            </div>
        </section>

        <?php
    // 페이지 콘텐츠 출력을 종료합니다.
    endwhile;
    ?>
</main>

<?php
// 사이트의 공통 푸터를 불러옵니다.
get_footer();
?>

이 코드에 추가된 주요 부분은 다음과 같습니다.

이 방식에서는 고정된 레이아웃은 PHP 템플릿에서 관리하고, 자주 바뀌는 내용은 워드프레스 관리자에서 수정할 수 있습니다.

예를 들어 다음 항목은 PHP 파일에 작성합니다.

반면 다음 항목은 워드프레스 편집기에서 관리합니다.

문의 양식 플러그인을 사용한다면 페이지 편집기에 양식 블록이나 숏코드를 추가할 수 있습니다. 플러그인 방식에 따라 해당 내용은 `the_content()` 출력 영역에 표시될 수 있습니다.

• 페이지 상단 소개 영역
• 섹션 배치
• 고정 안내 문구
• 서비스 소개 버튼
• 문의 페이지 전체 레이아웃
• 문의 안내 본문
• 문의 양식
• 이미지
• 추가 설명
• 블록으로 작성한 콘텐츠

특정 페이지에만 CSS 적용하기

문의 페이지에만 별도 스타일을 적용하려면 CSS 파일을 만들고 `functions.php`에서 조건부로 불러오면 됩니다.

먼저 차일드 테마에 다음 파일을 생성합니다.

/wp-content/themes/mytheme-child/assets/css/contact.css

이후 차일드 테마의 `functions.php`에 다음 코드를 추가합니다. 아래 코드는 공식 문서의 복사본이 아니라 이 글에서 구성한 구현 예제이며, 기존 함수와 충돌하지 않도록 프로젝트에 맞는 고유한 함수 이름을 사용해야 합니다.

<?php
/**
 * 문의 페이지에서만 전용 CSS 파일을 불러옵니다.
 */
function ible_enqueue_contact_page_styles() {
    // 현재 페이지 슬러그가 contact가 아니면 실행을 중단합니다.
    if ( ! is_page( 'contact' ) ) {
        return;
    }

    // 차일드 테마 내부의 CSS 파일 경로를 지정합니다.
    $stylesheet_path = get_stylesheet_directory()
        . '/assets/css/contact.css';

    // CSS 파일이 실제로 존재하지 않으면 실행을 중단합니다.
    if ( ! file_exists( $stylesheet_path ) ) {
        return;
    }

    // 문의 페이지 전용 CSS 파일을 워드프레스에 등록합니다.
    wp_enqueue_style(
        // 스타일 파일을 구분하기 위한 고유 이름입니다.
        'ible-contact-page',

        // 브라우저에서 불러올 CSS 파일 주소입니다.
        get_stylesheet_directory_uri() . '/assets/css/contact.css',

        // 다른 스타일 파일에 대한 의존성이 없다는 뜻입니다.
        array(),

        // 이 구현 예제에서는 파일 수정 시간을 CSS 버전 값으로 전달합니다.
        filemtime( $stylesheet_path )
    );
}

// 프런트엔드 스타일을 불러오는 시점에 함수를 실행합니다.
add_action(
    'wp_enqueue_scripts',
    'ible_enqueue_contact_page_styles'
);

이미 `functions.php` 파일의 첫 줄에 `<?php`가 있다면 위 코드의 `<?php`는 다시 추가하지 않습니다.

이 예제에서 `wp_enqueue_style()`은 CSS 파일을 워드프레스에 등록합니다. 매개변수와 사용 방식은 아래 공식 함수 문서에서 확인할 수 있으며, 나머지 조건문과 파일 검사는 이 글에서 구성한 구현 예제입니다.

이제 `contact.css` 파일에 스타일을 추가합니다.

/* 문의 페이지 내부 콘텐츠의 최대 너비를 설정합니다. */
.contact-page .container {
    width: min(100% - 40px, 1200px);
    margin-inline: auto;
}

/* 페이지 상단 소개 영역입니다. */
.contact-hero {
    padding: 96px 0 64px;
    background-color: #f5f7fa;
}

/* 상단에 표시되는 Contact 문구입니다. */
.contact-hero__label {
    margin: 0 0 12px;
    color: #44617b;
    font-size: 15px;
    font-weight: 600;
}

/* 페이지의 주요 제목입니다. */
.contact-hero__title {
    margin: 0 0 16px;
    font-size: clamp(32px, 5vw, 52px);
    line-height: 1.15;
}

/* 페이지 상단 안내 문구입니다. */
.contact-hero__description {
    max-width: 640px;
    margin: 0;
    color: #536273;
}

/* 문의 안내와 본문을 감싸는 영역입니다. */
.contact-details {
    padding: 72px 0;
}

/* 문의 안내와 본문을 두 개의 열로 배치합니다. */
.contact-details__grid {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: 48px;
}

/* 서비스 안내 버튼 스타일입니다. */
.contact-details__button {
    display: inline-block;
    margin-top: 20px;
    padding: 12px 20px;
    border-radius: 6px;
    background-color: #173a56;
    color: #ffffff;
    text-decoration: none;
}

/* 모바일 화면에서는 두 개의 열을 한 줄씩 표시합니다. */
@media (max-width: 767px) {
    .contact-hero {
        padding: 72px 0 48px;
    }

    .contact-details {
        padding: 48px 0;
    }

    .contact-details__grid {
        grid-template-columns: 1fr;
        gap: 32px;
    }
}

이 구현 예제에서는 `is_page( ‘contact’ )` 조건을 사용해 문의 페이지에서만 `contact.css`를 불러오도록 구성했습니다.

기존 테마에서도 `.container` 클래스를 사용한다면 클래스 충돌이 발생할 수 있습니다. 이런 경우에는 `contact-page__container`처럼 더 구체적인 이름으로 변경하면 됩니다.

참고: WordPress 공식 문서: wp_enqueue_style()

page-slug.php와 Template Name 방식 비교

특정 페이지에 전용 템플릿을 적용하는 방법은 `page-{slug}.php`만 있는 것은 아닙니다. `Template Name` 주석을 사용하면 관리자 화면에서 직접 선택할 수 있는 템플릿을 만들 수 있습니다.

먼저 다음 파일을 생성합니다.

/wp-content/themes/mytheme-child/template-landing.php

파일에 다음 코드를 작성합니다.

<?php
/**
 * Template Name: Custom Landing Page
 *
 * 관리자 화면에서 직접 선택할 수 있는
 * 재사용 가능한 페이지 템플릿입니다.
 */

// 사이트의 공통 헤더를 불러옵니다.
get_header();
?>

<main id="primary" class="site-main landing-page">
    <?php
    // 현재 페이지의 콘텐츠를 불러옵니다.
    while ( have_posts() ) :

        // 페이지 제목과 본문을 사용할 수 있도록 준비합니다.
        the_post();
        ?>

        <section class="landing-page__content">
            <div class="container">
                <h1>
                    <?php
                    // 현재 페이지 제목을 안전하게 출력합니다.
                    echo esc_html( get_the_title() );
                    ?>
                </h1>

                <div class="landing-page__body">
                    <?php
                    // 관리자에서 작성한 페이지 본문을 출력합니다.
                    the_content();
                    ?>
                </div>
            </div>
        </section>

        <?php
    // 페이지 콘텐츠 출력을 종료합니다.
    endwhile;
    ?>
</main>

<?php
// 사이트의 공통 푸터를 불러옵니다.
get_footer();
?>

핵심은 파일 상단의 다음 주석입니다. 아래는 파일 상단 주석 부분만 나타낸 예시입니다.

/**
 * Template Name: Custom Landing Page
 */

이 주석이 있으면 페이지 편집 화면에서 `Custom Landing Page` 템플릿을 직접 선택할 수 있습니다.

두 방식의 차이는 다음과 같습니다.

예를 들어 문의 페이지 하나만 별도로 구성한다면 `page-contact.php`가 편리합니다.

반면 여러 캠페인 페이지에 동일한 디자인을 적용하려면 `Template Name` 방식이 적합합니다.

/campaign-one/

/campaign-two/

/campaign-three/

위 세 페이지에 같은 랜딩 페이지 디자인을 적용해야 한다면 각각 다른 PHP 파일을 만드는 것보다 `template-landing.php` 하나를 만들어 선택하는 편이 관리하기 쉽습니다.

워드프레스 페이지 템플릿 우선순위

워드프레스는 페이지를 표시할 때 정해진 순서에 따라 사용할 템플릿 파일을 찾습니다.

일반적인 클래식 테마 페이지의 우선순위는 다음과 같습니다.

① 페이지에 직접 지정한 커스텀 템플릿 ② `page-{slug}.php` ③ `page-{id}.php` ④ `page.php` ⑤ `singular.php` ⑥ `index.php`

예를 들어 `contact` 페이지의 ID가 `42`라면 다음 파일들이 존재할 수 있습니다.

template-landing.php
page-contact.php
page-42.php
page.php
singular.php
index.php

페이지 편집 화면에서 `template-landing.php`를 직접 선택했다면 해당 파일이 먼저 적용됩니다.

별도의 템플릿을 선택하지 않았다면 다음 순서로 적용 여부를 확인합니다.

page-contact.php

page-42.php

page.php

singular.php

index.php

따라서 `page-contact.php`와 `page-42.php`가 모두 있다면 `page-contact.php`가 먼저 적용됩니다.

반대로 `page-contact.php`를 만들었는데 적용되지 않는다면 페이지 설정에서 다른 템플릿이 선택되어 있는지 먼저 확인해야 합니다.

참고: WordPress 공식 문서: Template Hierarchy

템플릿이 적용되지 않을 때 확인할 사항

`page-contact.php` 파일을 만들었는데 기존 화면이 그대로 표시된다면 다음 항목을 확인해 보세요.

페이지 슬러그와 파일 이름이 같은지 확인

페이지 슬러그가 다음과 같다면:

contact-us

템플릿 파일 이름도 동일하게 맞춰야 합니다.

page-contact-us.php

다음 파일 이름은 적용되지 않습니다.

page-contact.php

페이지 제목이 `문의하기`더라도 실제 슬러그가 `contact-us`라면 파일 이름은 `page-contact-us.php`입니다.

현재 활성화된 테마에 파일을 추가했는지 확인

차일드 테마가 활성화되어 있다면 다음 위치에 파일을 추가해야 합니다.

/wp-content/themes/mytheme-child/page-contact.php

다른 테마 폴더에 파일을 추가하면 적용되지 않습니다.

현재 사용 중인 테마는 워드프레스 관리자에서 `외모 → 테마`로 이동해 확인할 수 있습니다.

직접 선택한 템플릿이 있는지 확인

페이지 편집 화면에서 별도 템플릿이 선택되어 있다면 해당 파일이 `page-contact.php`보다 먼저 적용될 수 있습니다.

예를 들어 다음 템플릿이 직접 선택된 상태라면:

Custom Landing Page

`page-contact.php`가 존재해도 해당 템플릿이 우선 적용될 수 있습니다.

페이지 설정에서 기본 템플릿으로 변경한 뒤 다시 확인해 보세요.

파일을 테마 루트에 저장했는지 확인

슬러그 전용 템플릿은 테마 루트에 저장해야 합니다.

올바른 경로:

/wp-content/themes/mytheme-child/page-contact.php

다음 위치는 슬러그 전용 템플릿의 기본 위치가 아닙니다.

/wp-content/themes/mytheme-child/custom/page-contact.php

/wp-content/themes/mytheme-child/templates/page-contact.php

`Template Name`을 사용하는 선택형 템플릿과 `page-{slug}.php` 방식은 파일 구성 기준이 다를 수 있으므로 구분해야 합니다.

페이지가 실제로 게시되어 있는지 확인

다음 파일만 생성했다고 해서 `/contact/` 페이지가 자동으로 만들어지지는 않습니다.

page-contact.php

워드프레스 관리자에서 `contact` 슬러그를 가진 페이지를 생성하고 게시해야 합니다.

템플릿 파일은 페이지를 생성하는 기능이 아니라 이미 존재하는 페이지의 표시 방식을 변경하는 기능입니다.

캐시를 삭제했는지 확인

페이지 캐시가 활성화된 환경에서는 변경 전 HTML이 계속 보일 수 있으므로 다음 순서로 캐시를 비운 뒤 확인합니다.

① 워드프레스 캐시 플러그인의 페이지 캐시를 비웁니다. ② 호스팅에서 제공하는 서버 캐시를 비웁니다. ③ CDN이나 리버스 프록시 캐시를 사용한다면 해당 캐시를 비웁니다. ④ 브라우저 캐시를 비우거나 강력 새로고침을 실행합니다.

HTML은 변경되었는데 CSS만 적용되지 않는다면 템플릿 문제가 아니라 스타일 파일 캐시 문제일 수 있습니다.

페이지 빌더 템플릿이 별도 레이아웃을 출력하는지 확인

페이지 빌더를 사용 중이면 빌더의 템플릿 표시 조건이 문의 페이지에 별도 레이아웃을 출력하도록 설정됐는지 확인하세요. PHP 테마 템플릿과의 적용 방식은 빌더 제품과 설정에 따라 다르므로 해당 제품 문서를 함께 확인해야 합니다.

이 경우 다음 항목을 함께 확인해야 합니다.

• 현재 페이지에 적용된 빌더 템플릿
• 빌더의 표시 조건
• 테마에서 사용하는 기본 페이지 템플릿
• 페이지 편집 화면의 템플릿 설정

메인 페이지는 front-page.php가 우선할 수 있습니다

사이트 메인 페이지에는 일반 페이지와 다른 규칙이 적용될 수 있습니다.

예를 들어 다음과 같이 홈페이지를 만들었다고 가정하겠습니다.

페이지 제목: 홈
페이지 슬러그: home
페이지 템플릿: page-home.php

워드프레스의 `설정 → 읽기`에서 이 페이지를 정적 홈페이지로 지정한 경우, 테마에 다음 파일이 존재하면 해당 파일이 먼저 사용될 수 있습니다.

front-page.php

따라서 홈페이지 디자인을 수정하려면 `page-home.php`만 확인하지 말고 `front-page.php` 파일도 함께 확인해야 합니다.

블로그 글 목록 페이지도 일반 페이지와 다르게 `home.php`가 사용될 수 있습니다.

이름만 보면 `home.php`가 홈페이지 템플릿처럼 느껴질 수 있지만, 워드프레스에서는 일반적으로 블로그 글 목록에 사용되는 파일입니다.

참고: WordPress 공식 문서: Custom Front Page Templates

블록 테마에서는 템플릿 구조가 다를 수 있습니다

이 글에서 설명한 `page-contact.php` 방식은 PHP 템플릿을 사용하는 클래식 테마를 기준으로 합니다.

블록 테마에서는 일반적으로 HTML 기반 템플릿을 사용하며, 워드프레스 사이트 편집기에서 템플릿을 관리할 수 있습니다.

예를 들어 블록 테마에서는 다음과 같은 파일 구조를 사용할 수 있습니다.

/templates/page-contact.html

또는 사이트 편집기에서 특정 페이지에 적용할 템플릿을 만들어 관리할 수 있습니다.

따라서 사용 중인 테마가 블록 테마라면 `page-contact.php`를 추가하기 전에 현재 테마가 PHP 템플릿을 사용하는지, HTML 템플릿과 사이트 편집기를 사용하는지 먼저 확인해야 합니다.

마무리

워드프레스에서 특정 페이지만 다른 디자인으로 만들고 싶다면 페이지 슬러그에 맞는 `page-{slug}.php` 파일을 추가하면 됩니다.

예를 들어 `/contact/` 페이지를 개별적으로 구성하려면 활성화된 차일드 테마에 다음 파일을 만듭니다.

/wp-content/themes/mytheme-child/page-contact.php

파일에 `get_header()`, `the_content()`, `get_footer()`를 포함하면 기존 테마 구조를 유지하면서 원하는 HTML을 자유롭게 추가할 수 있습니다.

특정 페이지 하나만 개발한다면 `page-{slug}.php`가 간단하고, 같은 디자인을 여러 페이지에서 사용해야 한다면 `Template Name` 방식이 적합합니다.

페이지가 예상대로 표시되지 않을 때는 슬러그, 파일 위치, 활성화된 테마, 직접 지정한 템플릿, 캐시와 페이지 빌더 설정을 차례대로 확인하면 됩니다.