레이아웃 가이드

Thymeleaf Layout Dialect를 활용한 레이아웃 및 Fragment 사용법

최종 수정: 2026-05

레이아웃 가이드

레이아웃 구조

templates/
├── layout/
│   ├── default.html        # 일반 페이지 (헤더/푸터 포함)
│   ├── blank.html          # 어드민 페이지 (헤더/푸터 없음)
│   └── guide.html          # 개발 가이드 (사이드바 레이아웃)
├── fragments/
│   ├── header.html         # 사이트 헤더 fragment
│   ├── footer.html         # 사이트 푸터 fragment
│   ├── common-head.html    # meta + CDN + style.css
│   └── common-script.html  # APP_CONFIG + main.js
└── {domain}/               # 도메인별 화면

default.html (일반 레이아웃)

<!DOCTYPE html>
<html lang="ko"
      xmlns:th="http://www.thymeleaf.org"
      xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout">
<head>
    <!-- $CONTENT_TITLE — jihwan.dev 형식으로 자동 조합 -->
    <title layout:title-pattern="$CONTENT_TITLE — jihwan.dev">jihwan.dev</title>
    <th:block th:replace="~{fragments/common-head :: common-head}"></th:block>
    <th:block layout:fragment="page-css"></th:block>
</head>
<body>
    <th:block th:replace="~{fragments/header :: header}"></th:block>
    <div layout:fragment="content"></div>
    <th:block th:replace="~{fragments/footer :: footer}"></th:block>
    <th:block th:replace="~{fragments/common-script :: common-script}"></th:block>
    <th:block layout:fragment="page-script"></th:block>
</body>
</html>

Fragment 사용법

Fragment 정의

<!-- fragments/header.html -->
<header th:fragment="header" class="site-header">
    <nav>...</nav>
</header>

Fragment 포함 방법

<!-- th:replace — 태그 자체를 fragment로 교체 (권장) -->
<th:block th:replace="~{fragments/header :: header}"></th:block>

<!-- th:insert — 태그 안에 fragment 삽입 -->
<div th:insert="~{fragments/header :: header}"></div>

<!-- 파라미터 전달 -->
<th:block th:replace="~{fragments/alert :: alert('success', '저장되었습니다.')}"></th:block>

파라미터 받는 Fragment

<!-- fragments/alert.html -->
<div th:fragment="alert(type, message)"
     th:classappend="'alert-' + ${type}"
     class="alert">
    <span th:text="${message}"></span>
</div>

레이아웃 선택 기준

페이지 유형	레이아웃
일반 사용자 페이지	`layout/default`
어드민 페이지	`layout/blank`
개발 가이드	`layout/guide`

페이지 전용 CSS/JS

<!-- 페이지 전용 CSS -->
<th:block layout:fragment="page-css">
<link rel="stylesheet" th:href="@{/css/notes.css}">
</th:block>

<!-- 페이지 전용 스크립트 -->
<th:block layout:fragment="page-script">
<script th:src="@{/js/notes.js}"></script>
<script>
    // 인라인 초기화 코드
    const config = { page: 1 };
</script>
</th:block>

타이틀 패턴

<!-- layout/default.html 설정 -->
<title layout:title-pattern="$CONTENT_TITLE — jihwan.dev">jihwan.dev</title>

<!-- 페이지에서 -->
<title>게시글 목록</title>
<!-- 결과: "게시글 목록 — jihwan.dev" -->

<!-- 타이틀 미지정 시 → "jihwan.dev" (레이아웃 기본값) -->

공통 설정 파일 주의사항

common-head.html 및 common-script.html은 레이아웃이 자동 삽입하므로:

개별 페이지에서 style.css, main.js 중복 선언 금지
페이지 전용 에셋은 layout:fragment="page-css" / layout:fragment="page-script" 사용