Gulp file include
last modified November 15, 2026
In this article we build HTML pages from partials with Gulp 5. The gulp-file-include
plugin inserts files into pages, passes variables to them, repeats a partial for the items of a JSON file
and includes parts of a page conditionally.
HTML partials
Most sites repeat the same parts on every page: the header, the navigation and the footer. Without a template
engine we would copy them into every file and change them in many places. The gulp-file-include
plugin solves this at build time: a page contains directives such as @@include('header.html'),
and the plugin replaces them with the content of the files. The result is plain static HTML. The plugin
is a small alternative to template engines such as Nunjucks or Handlebars.
Installing the project
We create a project and install Gulp, the plugin and, for the last example, the HTML minifier from the Gulp HTML minify tutorial.
$ mkdir gulp-include $ cd gulp-include $ npm init -y $ npm i -D gulp gulp-file-include gulp-html-minifier-terser $ mkdir -p src/partials src/data
The example project
The pages are in src, the partials in src/partials and the data in
src/data. The tree shows the files; the gulpfile selects only src/*.html, so the
partials are not built as pages.
$ find src -type f | sort src/about.html src/data/links.json src/index.html src/links.html src/partials/card.html src/partials/footer.html src/partials/header.html src/partials/link.html
Partials with variables
The header partial contains @@title, a variable. The plugin replaces it with the value
that it finds in the variables of the include directive or, if there is none, in the global
context option.
<header>
<h1>@@title</h1>
<nav>
<a href="index.html">Home</a>
<a href="about.html">About</a>
</nav>
</header>
The footer uses two global variables, and the card is a reusable block for a title and a text.
<footer>
<p>© @@year @@author</p>
</footer>
<div class="card">
<h3>@@name</h3>
<p>@@text</p>
</div>
The home page includes the header, two cards with their own variables, and the footer. The variables of an include are a JSON object after the file name.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>@@title</title>
</head>
<body>
@@include('partials/header.html')
<main>
@@include('partials/card.html', { "name": "Gulp", "text": "A task runner." })
@@include('partials/card.html', { "name": "Sass", "text": "A CSS preprocessor." })
</main>
@@include('partials/footer.html')
</body>
</html>
The second page overrides the title variable for the header, and it shows a conditional block
and a variable that has only a global value.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>About - @@title</title>
</head>
<body>
@@include('partials/header.html', { "title": "About us" })
<main>
@@if (context.debug) {
<p>Debug build</p>
}
<p>Built with @@tool.</p>
</main>
@@include('partials/footer.html')
</body>
</html>
The gulpfile
The gulpfile has two tasks. The build task reads the pages, runs them through fileinclude and writes them to dist.
The global variables are defined once in the context object. The debug variable
comes from the DEBUG environment variable, which we use for the conditional block.
import { src, dest } from 'gulp';
import fileinclude from 'gulp-file-include';
import htmlmin from 'gulp-html-minifier-terser';
const context = {
title: 'My site',
author: 'Jan Bodnar',
year: 2026,
tool: 'Gulp 5',
debug: process.env.DEBUG === '1'
};
export function build() {
return src('src/*.html')
.pipe(fileinclude({
prefix: '@@',
basepath: '@file',
context
}))
.pipe(dest('dist'));
}
export function minified() {
return src('src/*.html')
.pipe(fileinclude({ prefix: '@@', basepath: '@file', context }))
.pipe(htmlmin({ collapseWhitespace: true, removeComments: true }))
.pipe(dest('dist-min'));
}
The prefix option is the string that starts a directive; @@ is the default.
The basepath option decides where the included files are looked up. The value
@file means relative to the file that contains the directive, so partials can include other
partials with a path that is relative to themselves. Other values are @root, relative to the
working directory, or a path such as src/partials.
Including files
We run the build task and look at the home page. The directives are replaced by the content of the
partials, and the variables with their values: the title is the global one, and every card has its own text.
The indentation of the partials is kept, so it does not match the indentation of the page; it is only
cosmetic, and we can minify the result.
$ npx gulp build
[13:40:06] Using gulpfile ~/Documents/prog/js/gulp-include/gulpfile.mjs
[13:40:06] Starting 'build'...
[13:40:06] Finished 'build' after 22 ms
$ cat dist/index.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>My site</title>
</head>
<body>
<header>
<h1>My site</h1>
<nav>
<a href="index.html">Home</a>
<a href="about.html">About</a>
</nav>
</header>
<main>
<div class="card">
<h3>Gulp</h3>
<p>A task runner.</p>
</div>
<div class="card">
<h3>Sass</h3>
<p>A CSS preprocessor.</p>
</div>
</main>
<footer>
<p>© 2026 Jan Bodnar</p>
</footer>
</body>
</html>
Variables and conditions
On the about page the include passes { "title": "About us" }, which wins over the
global title in the header, while the <title> element of the page still shows the global one.
The @@if directive includes its block only if the expression is true. The condition is
evaluated in JavaScript, with the context object available. Without the DEBUG
variable the block is not in the output; with it, the paragraph appears.
@@if (context.debug) {
<p>Debug build</p>
}
$ grep -c Debug dist/about.html 0 $ DEBUG=1 npx gulp build --silent $ grep -n Debug dist/about.html 19: <p>Debug build</p>
Loops
The @@loop directive repeats a partial for each item of an array. The array comes from a
JSON file or is written in the directive. The properties of the item are available as variables in the
partial. Here we build a list of links from a JSON file.
[
{ "text": "Gulp", "url": "https://gulpjs.com" },
{ "text": "Sass", "url": "https://sass-lang.com" },
{ "text": "Terser", "url": "https://terser.org" }
]
<li><a href="@@url">@@text</a></li>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Links</title>
</head>
<body>
<ul>
@@loop('partials/link.html', 'data/links.json')
</ul>
</body>
</html>
The links.html page has the @@loop directive with the partial and the data file.
Every item of the array produces one li element.
$ npx gulp build --silent
$ cat dist/links.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Links</title>
</head>
<body>
<ul>
<li><a href="https://gulpjs.com">Gulp</a></li>
<li><a href="https://sass-lang.com">Sass</a></li>
<li><a href="https://terser.org">Terser</a></li>
</ul>
</body>
</html>
Minifying the result
The plugin is only one step of the pipeline, so we can add more steps after it. The minified task
includes the partials and then minifies the pages with gulp-html-minifier-terser, which also removes the
uneven indentation. We compare the sizes of the pages before and after the minification.
export function minified() {
return src('src/*.html')
.pipe(fileinclude({ prefix: '@@', basepath: '@file', context }))
.pipe(htmlmin({ collapseWhitespace: true, removeComments: true }))
.pipe(dest('dist-min'));
}
The task is the second exported function of the gulpfile; both exported functions are tasks, as the ESM gulpfile tutorial explains.
$ npx gulp minified --silent $ wc -c dist/*.html dist-min/*.html 403 dist/about.html 514 dist/index.html 297 dist/links.html 305 dist-min/about.html 392 dist-min/index.html 258 dist-min/links.html 2169 total
Errors
If a partial does not exist, the plugin fails with a clear message, and the task stops with a non-zero exit code. We add a page that includes a missing file.
<body>@@include('partials/missing.html')</body>
The error names the plugin and the file that could not be opened.
$ npx gulp build 2>&1; echo "exit code: $?"
[13:40:07] Using gulpfile ~/Documents/prog/js/gulp-include/gulpfile.mjs
[13:40:07] Starting 'build'...
[13:40:07] 'build' errored after 19 ms
[13:40:07] Error in plugin "gulp-file-include"
Message:
ENOENT: no such file or directory, open '~/Documents/prog/js/gulp-include/src/partials/missing.html'
Details:
domainEmitter: [object Object]
domainThrown: false
exit code: 1
Source
gulp-file-include on npm, gulp-file-include on GitHub, Gulp src
In this article we have built HTML pages from partials with Gulp 5: we included files, passed variables, used conditions and loops, and minified the result. See also the Gulp HTML minify and Gulp watch tutorials.
Author
List all Gulp tutorials.