ZetCode

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.

src/partials/header.html
<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.

src/partials/footer.html
<footer>
    <p>&copy; @@year @@author</p>
</footer>
src/partials/card.html
<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.

src/index.html
<!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.

src/about.html
<!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.

gulpfile.mjs
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>&copy; 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.

src/data/links.json
[
    { "text": "Gulp", "url": "https://gulpjs.com" },
    { "text": "Sass", "url": "https://sass-lang.com" },
    { "text": "Terser", "url": "https://terser.org" }
]
src/partials/link.html
<li><a href="@@url">@@text</a></li>
src/links.html
<!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.

src/bad.html
<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

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Gulp tutorials.