photo credit: minds-eye via photopin cc

How to process HTML with grunt

Grunt is an indispensable tool when you’re in the business of web development. It takes away so much of the repetitive tasks for you so you can focus on what really matters. The other day I mentioned the use of Grunt in a basic build setup with Jenkins. One of the aspects of this build process was the use of the grunt-processhtml node package. In this article I’ll explain more in depth in what this package is, what it does and why you should use it.

The benefits

The benefits of a HTML processor are great. We all know that while you are developing a website, there are various reasons why your assets are different compared to a live environment. For example:

  • You want expanded, non mini- or uglified CSS and JavaScript so we can debug more easily.
  • Or you want to include some extra scripts that help us with debugging or testing.
  • Perhaps on development you load resources from another source than a live environment.

The problem with this, is that the HTML code on our production environment differs from our live environment. Where in development we include 20-30 external libraries, stylesheets and scripts, on a live environment we want to include 1 minified stylesheet and 1 uglified JavaScript file.


This is where grunt-processhtml comes in: it parses your HTML template and replaces whole blocks of HTML with a single tag. Say goodbye to keeping track of 2 HTML templates: you can easily compile this in your build script.


The most basic example is as follows:


This is a very basic build script. What it does is it loads path/to/header.php  and saves it to path/to/new_header.php .

HTML code

Say we have the above Grunt configuration and we have the following piece of code in path/to/footer.php :

The above HTML is going to be replaced by Grunt with:

It’s that simple!

Replacing in the same file

There are cases where you don’t want to create a new file, but rather overwrite the source file with the parsed file. Think of a deployment tool like Capistrano, where a branch in your Git repository is a reflection of the live site. In that case you simple set the source and the destination to the same path:

In conclusion

There are more actions possible with grunt-processhtml, but when it comes to building replacing the CSS and JavaScript are the most used. If you want more bang for your bucks, I suggest to check out the repository.
I hope this article gave you a bit of an idea on how to use this piece of code and I hope it helps you in your project.

Visitors give this article an average rating of 3.2 out of 5.

How would you rate this article?

6 thoughts on “How to process HTML with grunt”

  1. Tim says:

    Does the plugin actually do any minification automatically?

    In other words, do the files referenced by this block

    get read and concatenated and minified automatically using the processhtml plugin into this file:

    1. Giel Berkers says:

      No, the processhtml is merely a find-and-replace. To minify, uglify and concatenate you nees other packages.

  2. what about using grunt variables? for example, if i have this file name:
    and i want it to replace this file name:

    but only when i run grunt stage, as opposed to grunt dev

    can those variables be put into the build tag like this?
    <!– build:css build/js/_.min.js –>

  3. Dave says:

    I think you have the syntax reversed. At least in the current version of processhtml, the destination file comes first. So it should be

    files: {
    ‘path/to/new_header.php’ : [‘path/to/header.php’],
    ‘path/to/new_footer.php’ : [‘path/to/footer.php’]

    Check out the example on the npm site:

  4. vlrprbttst says:

    Dave is right, you inverted the syntax. thanks for the article, exactly what i was looking for 🙂

  5. Jeremy says:

    Thanks for explaining grunt-processhtml in a simple and intuitive manner. This being said, dave is right, the source and destination should be switched when specifying the file locations

Leave a Reply