Gulp NJK 세팅 - by. UXKM

2024-07-30

요약 설명

기본 html은 header, footer(이하 '공통 영역') 등을 include 할 수 없어서 기본 html로만 사이트를 구성하기에 큰 불편함이 있습니다.
asp, php, jsp 등의 언어를 사용하면 공통 영역을 별도의 파일로 생성 후 include 하여 편리하게 코드 관리를 할 수 있지만 각 언어에 맞는 서버 세팅이 필요합니다.
Gulp에서는 asp, php, jsp 같은 언어를 사용하지 않고 gulp-nunjucks-render라는 패키지를 이용해서 이러한 불편함을 해소하는 동시에 더 편리하게 html을 작성할 수 있습니다.

Gulp는 대략 4,000개의 패키지가 존재하고, html을 편집하는 대표적인 패키지는 gulp-nunjucks-render 외에 gulp-file-include, gulp-pug 등이 있습니다.
UXKM에서는 gulp-nunjucks-render가 가장 효율적이라 판단하였고, 실제 UXKM 웹사이트 제작에도 사용했던 플러그인이기에 gulp-nunjucks-render로 html 편집 커리큘럼을 진행합니다.

4.1.1. gulp-nunjucks-render란?

gulp-nunjucks-render(이하 'njk')란 모질라(mozilla)에서 제작한 HTML 기반의 구문에서 템플릿 상속을 표준 탑재하는 강력한 언어입니다.
njk는 많은 양의 html 작업환경에 존재하는 불편한 요소를 해소할 수 있으며, include 와 layout template 기능을 지원합니다.

javascript의 기본적인 문법(변수, 조건문, 반복문, 함수 등)에 대한 지식이 있다면 njk를 더 효율적으로 활용할 수 있습니다. 프로젝트 환경이나 디자인에 따라 레이아웃은 시시각각 변화하기 때문에 상황에 맞게 적절히 레이아웃의 변화를 주려면 javascript 기본 문법을 어느 정도 학습하는 것을 추천합니다.
javascript가 익숙하지 않아도 커리큘럼을 따라 하다 보면 njk를 활용한 기본 레이아웃을 완성할 수 있습니다.

4.1.2. html 폴더 세팅

njk를 활용하려면 파일 확장자를 *.html에서 *.njk로 변경해야 합니다.
src 폴더에 있는 *.njk 파일을 퍼블리싱 하면 Gulp는 *.html로 변환하여 dist 폴더에 생성합니다.

html 내부에 폴더와 파일 추가

기존 index.html을 index.njk로 변경 후 아래와 같이 html 폴더를 구성하고 코드를 복사하세요.
아래 코드 중 생소한 njk 문법이 있습니다. 다음 'Gulp NJK 문법' 페이지에서 자세하게 소개합니다.

html 폴더 구조 및 파일 생성

								/* 폴더와 파일을 구성하세요. */
								html __folder_name__
									_template __folder_name__
										_include __folder_name__
											_footer.njk __file_name__
											_header.njk __file_name__
										_json __folder_name__
											_gnb.json __file_name__
										_macro __folder_name__
											_macro.njk __file_name__
										_layout.njk __file_name__
									pages __folder_name__
										history.njk __file_name__
										intro.njk __file_name__
									index.njk __file_name__

언더바(_)가 있는 폴더와 파일은 빌드 되지 않는 퍼블리싱 단계에서만 필요한 폴더와 파일입니다.
예를 들어, _header.njk, _footer.njk 파일은 index.njk, intro.njk, history.njk 각각의 파일에 병합되어 빌드 됩니다.

_include 파일 세팅 (header, foorer)

								<footer class="footer">
									<address>© 2022 Gulp Setting</address>
								</footer>
								<!-- // footer -->

_header.njk에서는 _gnb.json의 data를 이용해서 메뉴를 구성합니다.
코드 적용 후 a 태그의 tab indent를 반복문 선언 라인에 맞춰주세요.

								<header class="header">
									<strong>Gulp Setting</strong>
									<nav>
										{%- for navgation in gnb_data %}
										<a href="{{ navgation.href }}">{{ navgation.name }}</a>
										{%- endfor %}
									</nav>
								</header>
								<!-- // header -->

_json 파일 세팅

_header.njk의 메뉴 구성에 사용되며, 메뉴 외에 json형식이 필요한 다른 부분에도 사용 가능합니다.

								{
									"gnb_data": [
										{
											"name": "home",
											"href": "/"
										},
										{
											"name": "intro",
											"href": "/pages/intro.html"
										},
										{
											"name": "history",
											"href": "/pages/history.html"
										}
									]
								}

_macro 파일 세팅

macro는 njk의 문법이며, 재사용 가능한 콘텐츠를 함수의 형태(function)로 정의하는 문법입니다.

								{%- macro image( class, src, alt, width="", height="auto" ) -%}
									<figure class="{{ class }}">
										<img src="{{ src }}" width="{{ width }}" height="{{ height }}">
										<figcaption>{{ alt }}</figcaption>
									</figure>
								{%- endmacro %}

_layout.njk 파일 세팅

공통 레이아웃 템플릿을 세팅하는 파일입니다.
하나의 레이아웃 템플릿으로 메인과 서브를 같이 세팅할 수도 있고. 메인과 서브를 분리해서 세팅할 수도 있습니다. 또한 서브의 레이아웃이 여러 개일 경우 각각의 레이아웃 템플릿으로 분리하여 세팅할 수 있습니다.

아래 include 문법은 njk의 정식 include 문법이 아닙니다. njk의 유일한 단점은 빌드 후 html 코드의 들여쓰기(Tab Indent) 정리가 의도대로 되지 않는다는 점입니다.
macro와 filter를 이용해서 들여쓰기를 수동으로 조절하여 단점을 보완할 수 있습니다.
또한 minus(-)기호를 사용하여 쓸데없는 빈 줄이 생기는 것을 방지합니다.
'Gulp NJK 문법' 페이지에서 자세하게 소개합니다.

								{%- macro include(fileName) -%}
									{%- include fileName ignore missing -%}
								{%- endmacro -%}
								{#- // 들여쓰기(Tab Indent) 조정을 위한 macro -#}

								<!DOCTYPE html>
								<html lang="ko">
								<head>
									<meta charset="UTF-8">
									<title>Gulp Setting</title>
									<link href="/assets/css/style.min.css" rel="stylesheet" />
								</head>
								<body>
								<div class="wrap">
									{{ include( "_templates/_include/_header.njk" ) | tabIndent(1) }}

									<main class="container">
										{% filter tabIndent(1) %}
											{% block content %}
											{% endblock %}
										{%- endfilter %}
									</main>
									<!-- // content -->

									{{ include( "_templates/_include/_footer.njk" ) | tabIndent(1) }}
								</div>
								<!-- //wrap -->

								<script src="/assets/js/main.min.js"></script>
								</body>
								</html>

페이지(메인, 서브) 파일 세팅

페이지의 소스를 보면 단순합니다. 레이아웃은 없고 콘텐츠로만 구성되어 있습니다.
레이아웃은 _layout.njk 파일을 병합하여 빌드 하게 되고, 각각의 페이지에서는 block content 안에 콘텐츠만 적용합니다.
index.njk에는 macro를 적용하기 위해 _macro.njk를 import 합니다.

								{%- extends "_templates/_layout.njk" -%}
								{%- import "_templates/_macro/_macro.njk" as macro -%}

								{% block content %}
									<h1>index 페이지 입니다.</h1>
									{{ macro.image( "image_box", "/assets/images/visual.png", "메인 이미지 입니다.", width="400px" ) }}
								{%- endblock %}

								{%- extends "_templates/_layout.njk" -%}

								{% block content %}
									<h1>history 페이지 입니다.</h1>
								{%- endblock %}

								{%- extends "_templates/_layout.njk" -%}

								{% block content %}
									<h1>intro 페이지 입니다.</h1>
								{%- endblock %}

4.1.3. njk 및 부가 패키지 설치

터미널에서 아래 명령을 실행하여 njk(gulp-nunjucks-render)와 html 빌드에 필요한 부가적인 패키지를 설치합니다.

gulp-nunjucks-render

html을 편집을 위한 메인 패키지 입니다.

gulp-plumber

Gulp는 스트림을 파이프로 연결해 빌드를 수행하기 때문에, 에러가 발생하면 파이프를 타고 전달돼 전체 프로세스가 종료되어 버립니다.
만약, gulp.watch()를 걸어둔 상태라면 문법 에러 정도로 프로세스가 종료되어버려 아주 불편할 수 있습니다.
gulp-plumber를 적용하면 에러 발생 시 error log를 console로 출력한 후 'end' 이벤트를 발생시켜 현재 스트림을 종료하도록 합니다.
에러를 처리했기 때문에, 다른 프로세스는 정상적으로 진행됩니다.
css, js에도 적용할 수 있습니다.

gulp-cached

Gulp는 해당 task의 src 경로에 있는 파일 중 하나의 파일이 수정이 되도 src 경로 내 모든 파일을 다시 빌드 하게 됩니다.
예를 들어, intro.html, history.html, sitemap.html 이렇게 3개의 html이 있다는 가정하에 history.html 파일만 수정이 되더라도 Gulp는 나머지 intro.html, sitemap.html도 같이 빌드 합니다.
html 파일의 개수가 적을 경우는 문제가 없지만 몇 십, 몇 백 개의 html 파일이 존재할 경우에는 그만큼 빌드 시간이 길어집니다.
gulp-cached를 사용하면 파일의 캐시를 저장한 다음, 수정되는 파일만 감지하여 빌드 하게 되므로 시간을 절약할 수 있습니다.

gulp-data

json, front-matter, 데이터베이스 등 다양한 소스의 데이터를 pipe에 직접 삽입하여 데이터가 적용 되도록 할 수 있습니다.
예를 들어, gnb.json 데이터를 html에 적용하여 navigation 메뉴를 생성할 수 있습니다.

fs

fs는 filesystem의 약어입니다. 파일 시스템에 접근하는 모듈로, 파일을 생성, 삭제, 읽기, 쓰기 등을 할 수 있습니다.
본 커리큘럼에서는 json 파일을 읽어오는 데에 사용됩니다.

del

지정한 디렉터리를 삭제하는 기능입니다.
dist 폴더를 항상 최신 소스로 유지 하기 위해 Gulp가 실행 될 때마다 dist 폴더를 삭제한 후 다시 빌드하게 됩니다.

4.1.4. gulpfile.babel.js 세팅

이 섹션에서 njk 및 Gulp의 전반적인 흐름을 세팅합니다.
gulpfile.babel.js 파일의 기존 코드를 지우고 아래 코드를 적용합니다.
영역별 설명은 주석으로 대체합니다.

							// import -----------------------------------------------------------
							import gulp from "gulp";
							import nunjucksRender from "gulp-nunjucks-render";
							import plumber from "gulp-plumber";
							import data from "gulp-data";
							import cached from "gulp-cached";
							import fs from "fs";
							import del from "del";


							// routes -----------------------------------------------------------
							const src = './src';
							const dist = './dist';
							const ass = '/assets';

							// src 폴더의 경로 설정
							const path_src = {
								html: src + '/html',
								css: src + ass + '/css',
								images: src + ass + '/images',
								js: src + ass + '/js',
							}

							// 빌드될 dist 폴더의 경로 설정
							const path_dist = {
								html: dist,
								css: dist + ass + '/css',
								images: dist + ass + '/images',
								js: dist + ass + '/js',
							};


							// etc --------------------------------------------------------------
							const onErrorHandler = (error) => console.log(error);  // plumber option (에러 발생 시 에러 로그 출력)


							// task -------------------------------------------------------------

							// html task
							const html = () => {
								// 들여쓰기(Tab Indent) 조정을 위한 함수
								const manageEnvironment = (environment) => {
									environment.addFilter('tabIndent', (str, numOfIndents, firstLine) => {
										str = str.replace(/^(?=.)/gm, new Array(numOfIndents + 1).join('\t'));
										if(!firstLine) {
											str = str.replace(/^\s+/, "");
										}
										return str;
									});
								};

								// _gnb.json 파일 적용을 위한 변수
								const gnbJson = JSON.parse(fs.readFileSync(path_src.html + '/_templates/_json/_gnb.json'));
								const json_all = {...gnbJson};
								const datafile = () => {
									return json_all;
								}

								// njk 빌드
								return gulp.src([
									path_src.html + '/**/*',                           // 빌드할 njk 파일 경로
									'!' + path_src.html + '/**/_*',                    // 경로 중 제외할 njk 파일(빌드 때 병합될 파일)
									'!' + path_src.html + '/**/_*/**/*'                // 경로 중 제외할 폴더 및 폴더의 njk 파일(빌드 때 병합될 파일)
								])
								.pipe( plumber({errorHandler:onErrorHandler}) )      // 에러 발생 시 gulp 종료 방지 및 에러 핸들링
								.pipe( data( datafile) )                             // _gnb.json 적용
								.pipe( nunjucksRender({                              // njk 적용
									envOptions: {                                      // njk 옵션 설정
										autoescape: false,                               // njk 문법의 오류가 있더라도 진행
									},
									manageEnv: manageEnvironment,                      // 들여쓰기(Tab Indent) 함수 적용
									path: [path_src.html],                             // html 폴더 전체 경로
								}) )
								.pipe( cached('html') )                              // 변경된 파일 캐시 저장
								.pipe( gulp.dest(path_dist.html) )                   // 빌드 후 html 파일이 생성될 목적지 설정
							}

							// clean task
							const clean = () => del([dist]);                       // dist 폴더 삭제


							// series & parallel (task 그룹화) ----------------------------------

							// 순차적으로 실행되어야 하는 task 그룹
							const prepare = gulp.series([ clean ]);

							// 위 prepare 실행 완료 후 순차적으로 실행되어야 하는 task 그룹
							const assets = gulp.series([ html ]);


							// export (gulp 실행 명령어) ----------------------------------------

							// gulp build 실행 (prepare 실행 후 assets 실행)
							export const build = gulp.series([ prepare, assets ]);

							// gulp dev 실행 (build 실행)
							export const dev = gulp.series([ build ]);

4.1.5. gulp dev 실행

gulpfile.babel.js 파일을 세팅한 후 터미널에서 아래 명령을 실행합니다.

Gulp가 샐행되고 터미널에 Gulp의 작업 내용이 출력됩니다.

gulp dev 실행시 터미널에 작업내용 출력

세팅이 잘 되었다면 터미널에 위와 같은 메시지가 출력 되고, gulpfile.babel.js에 세팅한 순서대로 작업이 진행된 것을 볼 수 있습니다.

dev 시작
dist 폴더 삭제를 위해 clean task 시작 및 dist 폴더 삭제 후 종료
html 빌드를 위해 html task 시작 및 njk를 html로 변환하여 dist 폴더에 생성 후 종료
dev 종료

그리고 폴더를 확인해 보면 아래 이미지처럼 dist 폴더와 html 파일이 생성된 것을 확인할 수 있습니다.
_template 폴더의 모든 파일은 html 파일에 병합되었기 때문에 dist 폴더에는 html 파일만 있는 게 맞습니다.

gulp dev 실행 후 dist 폴더 및 파일 생성

4.1.6. 빌드 된 html 코드 확인

깔끔한 들여쓰기(Tab Indent)와 쓸데없는 공백이 없는지 확인해 봅니다.
각각의 html 피일이 아래 코드와 같은 상태인지 확인해 보세요.

							<!DOCTYPE html>
							<html lang="ko">
							<head>
								<meta charset="UTF-8">
								<title>Gulp Setting</title>
								<link href="/assets/css/style.min.css" rel="stylesheet" />
							</head>
							<body>
							<div class="wrap">
								<header>
									<strong>Gulp Setting</strong>
									<nav>
										<a href="/">home</a>
										<a href="/pages/intro.html">intro</a>
										<a href="/pages/history.html">history</a>
									</nav>
								</header>
								<!-- // header -->

								<main class="container">
									<h1>index 페이지 입니다.</h1>
									<figure class="image_box">
										<img src="/_assets/images/visual.png" width="400px" height="auto">
										<figcaption>메인 이미지 입니다.</figcaption>
									</figure>
								</main>
								<!-- // content -->

								<footer>
									<address>© 2022 Gulp Setting</address>
								</footer>
								<!-- // footer -->
							</div>
							<!-- //wrap -->

							<script src="/_assets/js/main.min.js"></script>
							</body>
							</html>

							<!DOCTYPE html>
							<html lang="ko">
							<head>
								<meta charset="UTF-8">
								<title>Gulp Setting</title>
								<link href="/assets/css/style.min.css" rel="stylesheet" />
							</head>
							<body>
							<div class="wrap">
								<header>
									<strong>Gulp Setting</strong>
									<nav>
										<a href="/">home</a>
										<a href="/pages/intro.html">intro</a>
										<a href="/pages/history.html">history</a>
									</nav>
								</header>
								<!-- // header -->

								<main class="container">
									<h1>history 페이지 입니다.</h1>
								</main>
								<!-- // content -->

								<footer>
									<address>© 2022 Gulp Setting</address>
								</footer>
								<!-- // footer -->
							</div>
							<!-- //wrap -->

							<script src="/_assets/js/main.min.js"></script>
							</body>
							</html>

							<!DOCTYPE html>
							<html lang="ko">
							<head>
								<meta charset="UTF-8">
								<title>Gulp Setting</title>
								<link href="/assets/css/style.min.css" rel="stylesheet" />
							</head>
							<body>
							<div class="wrap">
								<header>
									<strong>Gulp Setting</strong>
									<nav>
										<a href="/">home</a>
										<a href="/pages/intro.html">intro</a>
										<a href="/pages/history.html">history</a>
									</nav>
								</header>
								<!-- // header -->

								<main class="container">
									<h1>intro 페이지 입니다.</h1>
								</main>
								<!-- // content -->

								<footer>
									<address>© 2022 Gulp Setting</address>
								</footer>
								<!-- // footer -->
							</div>
							<!-- //wrap -->

							<script src="/_assets/js/main.min.js"></script>
							</body>
							</html>

여기까지 html 편집을 위한 njk(gulp-nunjucks-render) 세팅이 마무리됐습니다.
njk를 활용하여 더 효율적이고 합리적인 html을 구성하고 싶다면 Gulp NJK 문법 페이지의 내용이 많은 도움이 될 것입니다.

아직은 Gulp 세팅이 마무리되지 않았기 때문에 html이 정상 작동하지 않습니다.
html이 브라우저에서 열리겠지만 css, js, image가 동작하지 않습니다. 아직 html 편집에 대한 세팅만 마무리됐기 때문에 당연한 결과입니다.

다음 커리큘럼에서는 Web Server를 구축하여 gulp dev 실행 시 자동으로 브라우저를 띄워 html을 열고,
gulp.watch로 파일의 변경, 업데이트를 감지하여 새로고침 없이 실시간으로 브라우저에 반영하는 방법을 알아보겠습니다.

아래 내용은 선택사항으로 건너띄워도 커리큘럼 진행에 문제가 되지 않습니다.

4.1.7. 에디터기에서 njk 문법 활성화 (WebStorm 기준)

확장자가 njk인 파일에서만 사용되는 특수 문법은 에디터에서 인식되지 않아서 단색으로만 표시됩니다. 이는 퍼블리싱 작업에 직접적인 문제를 일으키지는 않지만, 불편을 겪을 수 있습니다.

Twig를 이용해서 이 문제를 해결할 수 있습니다.
Twig는 PHP 템플릿 엔진으로, Symfony 프레임워크 및 다른 PHP 프로젝트에서 널리 사용되며, 강력한 기능을 제공합니다.
Twig를 설치하고 [file name patterns]에 njk를 추가하여 Twig가 njk 문법을 인식하도록 설정할 수 있습니다.
이렇게 하면 에디터가 njk 파일을 올바르게 인식하고 적절한 문법 강조를 제공할 수 있게 됩니다.

WebStorm 기준으로 njk 문법 활성화 방법을 설명합니다.

Twig install
[설정(Settings..) > Plugins] 에서 Twig을 검색하고 설치합니다.
njk 파일 패턴 추가
[설정(Settings..) > Editor > File Types] 에서 Twig을 찾고, [file name patterns]에서 *.njk 페턴을 추가합니다.
Tab indent 설정
[설정(Settings..) > Editor > Code Style > Twig] 에서 각각의 항목을 아래 이미지처럼 수정합니다.

Twig 설치 및 세팅을 마친 후 코드를 확인하면 단색이었던 njk 문법이 활성화되어 있는 것을 확인할 수 있습니다.