The Simplest Ways to Handle HTML Includes
It’s extremely surprising to me that HTML has never had any way to include other HTML files within it. Nor does there seem to be anything on the horizon that addresses it. I’m talking about straight up includes, like taking a chunk of HTML and plopping it right into another. For example the use case for much of the entire internet, an included header and footer for all pages:
...
<body>
<include src="./header.html"></include>
Content
<include src="./footer.html"></include>
</body>
...That’s not real, by the way. I just wish it was.
People have been looking to other languages to solve this problem for them forever. It’s HTML preprocessing, in a sense. Long before we were preprocessing our CSS, we were using tools to manipulate our HTML. And we still are, because the idea of includes is useful on pretty much every website in the world.
Use PHP
Can you use PHP instead?
...
<body>
<?php include "./header.html" ?>
Content
<?php include "./footer.html" ?>
</body>
...This will perform the include at the server level, making the request for it happen at the file system level on the server, so it should be far quicker than a client-side solution.
Use Gulp
What’s even faster than a server-side include? If the include is preprocessed before it’s even on the server. Gulp has a variety of processors that can do this. One is gulp-file-include.
That would look like this:
...
<body>
@@include('./header.html')
Content
@@include('./footer.html')
</body>
...And you’d process it like:
var fileinclude = require('gulp-file-include'),
gulp = require('gulp');
gulp.task('fileinclude', function() {
gulp.src(['index.html'])
.pipe(fileinclude({
prefix: '@@',
basepath: '@file'
}))
.pipe(gulp.dest('./'));
});Looks like this particular plugin has fancy features where you can pass in variables to the includes, making it possible to make little data-driven components.
Use Grunt
This is what the grunt-bake plugin does. You’d configure Grunt to process your HTML:
grunt.initConfig({
bake: {
your_target: {
files: {
"dist/index.html": "app/index.html",
}
}
}
});Then your HTML can use this special syntax for includes:
...
<body>
<!--(bake header.html)-->
Content
<!--(bake footer.html)-->
</body>
...Use Handlebars
Handlebars has partials.
You register them:
Handlebars.registerPartial('myPartial', '{{name}}')Then use them:
{{> myPartial }}There is also fancy features of this that allow for evaluation and passing data. You’ll still need a processor to run it, probably something like gulp-handlebars.
Speaking of templating languages which make use of curly braces… Mustache has them, too.
Use Pug
Pug is an HTML preprocessor that has a whole new syntax for HTML that is a bit more terse. It’s got includes though.
...
body
include ./header.html"
p Content
include ./footer.html"
...Then you run it with something like gulp-pug.
Use Nunjucks
I love me some Nunjucks! Nunjucks has includes. You’d do it like this:
...
<body>
{% include "./header.html" %}
Content
{% include "./footer.html" %}
</body>
...If you put that in a file called index.njk, you could process it with a simple Node script into index.html like this:
const nunjucks = require("nunjucks");
const fs = require("fs");
fs.writeFile("index.html", nunjucks.render("index.njk"), function(err, data) {
if (err) console.log(err);
console.log("Compiled the Nunjucks, captain.");
});Or process it with something like gulp-nunjucks.
11ty has Nunjucks built-in, along with many of the other mentioned so far. Might be good for you if you’re actually building a little site.
Use Ajax
Say you had…
<body>
<header></header>
Content.
<footer></footer>
</body>You could fetch the contents for the header and footer from respective files and dump the contents in.
fetch("./header.html")
.then(response => {
return response.text()
})
.then(data => {
document.querySelector("header").innerHTML = data;
});
fetch("./footer.html")
.then(response => {
return response.text()
})
.then(data => {
document.querySelector("footer").innerHTML = data;
});Speaking of JavaScript… If you’re building your site using a JavaScript framework of just about any kind, building through components is kind of the main deal there and breaking parts you want to include in other files should be no problem. Some kind of import Header from "./header.js"; and
Use iframes
You could do this:
<body>
<iframe src="./header.html"></iframe>
Content.
<iframe src="./footer.html"></iframe>
</body>But the content in those iframes does not share the same DOM, so it’s a bit weird, not to mention slow and awkward to style (since iframes don’t know the heights of their contents).
Scott Jehl documented a cool idea though: You can have the iframe inject the content of itself onto the parent page then remove itself.
<body>
<iframe src="header.html" onload="this.before((this.contentDocument.body||this.contentDocument).children[0]);this.remove()"></iframe>
Content.
<iframe src="footer.html" onload="this.before((this.contentDocument.body||this.contentDocument).children[0]);this.remove()"></iframe>
</body>Use Jekyll
Jekyll is a Ruby-based static site generator with includes. You keep your includes in the /_includes/ folder, then:
<body>
{% include header.html %}
Content.
{% include footer.html %}
</body>Jekyll is a big one, so I’m calling it out here, but there are a ton of static site generators and I’d wager any of them can do includes.
Use Sergey
OK, I’ll call out one more SSG because it’s new and super focused. Sergey has a web components style format:
<body>
<sergey-import src="header" />
Content.
<sergey-import src="footer" />
</body>You’d name the files header.html and footer.html and put them in /includes/ and then it’ll make a build with the includes processed when you run the npm script it has you do.
Use Apache SSI
Apache, a super duper common web server, can do includes. You do it like this:
<body>
<!--#include file="./header.html" -->
Content
<!--#include file="./footer.html" -->
</body>But you need the right Apache configuration to allow stuff. I tried my best to get a working demo going but didn’t have much luck.
I tried using .htaccess within a folder on an Apache server and flipping on what I thought was the right stuff:
Options +Includes
AddType text/html .html
AddOutputFilter INCLUDES .htmlI’m sure there is some way to get it working though, and if you do, it’s kinda neat that it needs zero other dependencies.
Use CodeKit
Mac only, but CodeKit has a special language called Kit it processes where 90% of the point of it is HTML includes. It uses special HTML comments:
...
<body>
<!-- @import "./header.html" -->
Content
<!-- @import "./footer.html" -->
</body>
...Use Dreamweaver
Lol jk. But it really is a thing. DWTs, baby.
Holy Crap
That’s a lot of ways, isn’t it?
Like I said at the top, it’s very surprising to me that HTML itself hasn’t addressed this directly. Not that I think it would be a great idea for performance to have statements that trigger network requests all over our code, but it seems in-line with the platform. Using ES6 imports directly without bundling isn’t a great idea always either, but we have them. @importing CSS within CSS isn’t a great idea always, but we have it. If the platform had a native syntax, perhaps other tooling would key off that, much like JavaScript bundlers support the ES6 import format.
The post The Simplest Ways to Handle HTML Includes appeared first on CSS-Tricks.
