Gulp NJK 세팅 - by. UXKM

Gulp
HTML 편집 (Gulp NJK)
Gulp NJK 세팅

요약 설명

기본 HTML만으로는 header, footer 같은 공통 영역(이하 '공통 영역')을 include할 수 없어 사이트를 구성하는 데 큰 불편함이 있습니다.
ASP, PHP, JSP 같은 서버 사이드 언어를 사용하면 공통 영역을 별도의 파일로 분리하여 include할 수 있지만, 이를 위해서는 각 언어에 맞는 서버 환경을 따로 설정해야 하는 번거로움이 있습니다.
하지만 Gulp에서는 이러한 서버 언어 없이도 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는 Gulp 작업 흐름에서 Nunjucks 템플릿 엔진을 사용하여 HTML 파일을 효율적으로 작성하고 렌더링할 수 있도록 도와주는 플러그인입니다.
Nunjucks(이하 njk)는 모질라(Mozilla)에서 개발한 HTML 기반 템플릿 언어로, 템플릿 상속과 include, layout 기능을 표준으로 지원하며, 반복적이고 비효율적인 HTML 작성 과정을 크게 줄여줍니다.

정적 웹사이트 개발 시 njk를 사용하면 header, footer 같은 공통 영역을 재사용하거나, 디자인 구조에 따라 유연하게 레이아웃을 조정할 수 있어 유지보수가 쉬워집니다.

또한, njk는 JavaScript의 기본 문법(변수, 조건문, 반복문 등)을 기반으로 동작하기 때문에, JavaScript에 대한 이해가 있다면 더 효율적으로 활용할 수 있습니다.
다만, JavaScript에 익숙하지 않더라도 커리큘럼을 따라가면 기본적인 템플릿 구성과 레이아웃 작성은 충분히 가능하므로 부담 없이 학습할 수 있습니다.

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 작업(예: SCSS 컴파일, 템플릿 렌더링 등)을 하다 보면 작은 문법 오류 하나에도 전체 Gulp 프로세스가 멈추는 일이 발생할 수 있습니다. 이럴 경우 매번 Gulp를 다시 실행해야 해서 매우 번거롭고 작업 흐름이 끊깁니다.
gulp-plumber는 Gulp에서 사용하는 에러 처리용 플러그인으로, 작업 도중 에러가 발생해도 Gulp 프로세스가 중단되지 않도록 도와줍니다.

gulp-plumber를 사용하면:: 에러가 발생해도 Gulp가 중단되지 않고 계속 작동합니다.; 에러 메시지를 콘솔에 출력하여 문제 원인을 확인할 수 있습니다.; 개발 중 자동 리로드나 watch 기능이 끊기지 않습니다.

gulp-cached

Gulp는 기본적으로 src 경로 내 파일 중 하나라도 변경되면, 해당 경로에 포함된 모든 파일을 다시 처리합니다. 예를 들어 history.html 하나만 수정해도, intro.html, sitemap.html 등 나머지 파일들도 함께 빌드 대상이 됩니다. 파일 수가 많을 경우 이로 인해 빌드 시간이 비효율적으로 길어질 수 있습니다.
gulp-cached는 파일의 변경 여부를 캐시에 저장해, 변경된 파일만 Gulp task에서 처리하도록 만들어 줍니다. 이 방식은 특히 정적 HTML, 이미지, Sass, JavaScript 파일이 많은 프로젝트에서 처리 시간을 크게 줄이는 데 효과적입니다.

gulp-data

gulp-data는 Gulp에서 사용하는 템플릿 엔진(Nunjucks, e.g. Pug, Handlebars 등)에 외부 데이터를 주입하기 위해 사용되는 플러그인입니다.
JSON 파일, front-matter, API 응답, 데이터베이스 결과 등 다양한 형태의 데이터를 템플릿 렌더링 시점에 동적으로 삽입할 수 있습니다.

예를 들어, gnb.json 파일에 정의된 내비게이션 데이터를 불러와 HTML 템플릿에 삽입하면, 메뉴 항목을 코드 없이 데이터만으로 관리할 수 있습니다. gulp-data는 각 파일의 경로 정보를 활용해, 파일별로 다른 데이터를 적용할 수 있는 점도 큰 장점입니다.

핵심 기능: Gulp 스트림 안에서 외부 데이터를 불러와 템플릿에 주입할 수 있습니다.; JSON, YAML, front-matter, 동적 함수, DB 쿼리 등 다양한 데이터 소스 사용 가능합니다.; 템플릿 파일 단위로 다른 데이터 적용이 가능합니다. (예: 파일명 기반 매핑); 주로 gulp-nunjucks, gulp-pug 등과 함께 사용합니다.

fs

fs는 Node.js에서 기본으로 제공하는 파일 시스템(File System) 모듈로, 파일이나 디렉토리에 접근하여 생성, 읽기, 쓰기, 삭제 등의 작업을 수행할 수 있게 해줍니다.
이 모듈을 사용하면 텍스트 파일, JSON 파일, 이미지 파일 등 다양한 파일을 Node.js 코드에서 직접 다룰 수 있으며, 동기(fs.readFileSync)와 비동기(fs.readFile) 방식 모두 지원합니다.
본 커리큘럼에서는 fs를 사용해 JSON 파일을 읽고, 그 데이터를 njk 빌드 과정에 활용하는 데 사용됩니다.

del

del은 Node.js에서 사용하는 파일 및 폴더 삭제용 유틸리티로, Gulp 등 빌드 도구에서 불필요한 파일이나 디렉터리를 제거할 때 사용됩니다.
주로 dist, build, temp와 같은 결과물 폴더를 빌드 전에 먼저 삭제하여 항상 최신 상태로 재생성할 수 있게 도와줍니다.
Gulp에서는 dist 폴더를 항상 최신 상태로 유지하기 위해, 작업 실행 전 del을 사용해 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 작업 시작 → 삭제 완료 후 종료
HTML 빌드를 위한 html task 작업 시작 → *.njk 파일을 *.html로 변환하여 dist 폴더에 생성 → 작업 종료
dev 작업 종료

작업이 완료된 후 폴더를 확인해 보면, dist 폴더가 생성되어 있고 그 안에 변환된 HTML 파일들이 포함되어 있는 것을 볼 수 있습니다.
_template 폴더에 있던 파일들은 모두 병합되어 HTML 파일로 빌드되었기 때문에, dist 폴더에는 pages 폴더와 HTML 파일만 존재하는 것이 정상입니다.

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

4.1.6. 빌드 된 html 코드 확인

빌드가 완료된 후 생성된 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) 세팅이 마무리됐습니다.
더 효율적이고 체계적인 HTML 구성을 원한다면 Gulp NJK 문법 페이지를 참고하는 것을 추천합니다.
Gulp NJK 문법 바로가기

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

다음 단계에서는 웹 서버를 구축하여 gulp dev 실행 시 자동으로 브라우저를 열고, gulp.watch를 통해 파일 변경 사항을 감지해 실시간으로 브라우저에 반영하는 방법을 알아보겠습니다.

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

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

njk 특수 문법은 에디터에서 기본적으로 인식되지 않아 단색으로 표시되는 경우가 많습니다. 이는 퍼블리싱 작업에 직접적인 영향을 주지는 않지만, 작업 시 불편함을 초래할 수 있습니다.

이 문제는 Twig 플러그인을 활용해 해결할 수 있습니다.
Twig는 Symfony 등 PHP 프레임워크에서 널리 사용되는 템플릿 엔진으로, njk와 유사한 문법 구조를 가지고 있어 문법 강조에 적합합니다.
플러그인을 설치한 후 [file name patterns]에 *.njk를 추가하면, 에디터에서 njk 파일도 Twig 문법으로 인식하게 되어 보다 쾌적한 개발 환경을 만들 수 있습니다.

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 문법이 활성화되어 있는 것을 확인할 수 있습니다.