Including Files Using Straight HTML
Getting the job done for a particular task always calls forth the need for the proper set of tools. In this particular case, the task was to create a single-page static html content-rich site. When I say the site is “content-rich” what I actually mean is that there are paragraphs upon paragraphs of copy: text, images, etc.
Editing a giant HTML page no different than editing a large file of code written in any other language: it is a maintenance nightmare and so it is what you call not fun.
Searching for Solutions
I knew about jekyll and of course since I love it so much, I wanted to use it, however jekyll is way too much for what is needed. All I really need for this particular project is a way to use include statements in HTML.
Server-Side Options
There are a number of different ways to include one HTML document inside of another, but none of these methods are incorporated by using HTML directly by itself. Anyone who is familiar with PHP is familiar with the PHP [include]php-include function:
<?php include("myfile.html") ?>while those who haven’t used php who have used apache or Microsoft IIS are familiar with SSI, which may appear in the form of something like:
<!--#include virtual="myfile.html" -->
Neither one of these options seemed all too appealing to me. They both required some kind of processing from a server which is not testable offline without running a local server and also requires processing on every page hit.
What I really wanted was a way to be able to do this offline, and “build” my site by piecing it together somehow.
Building Offline
Here are the other methods I came across, starting with the simplest ideas of my own and moving on to the better ideas that I came across on the web.
The Unix cat Utility
The first thing I came up with was using cat. In case you don’t know, cat is
the unix utility which concatenates multiple files. This was my sure-fire way to
get the project moving assuming I couldn’t come up with something better. cat
has a few advantages and disadvantages.
Advantages to using cat:
- I already know how to use it
- It’s fairly simple
- There’s no way it won’t work
Disadvantages to using cat:
- It is extremely messy
- It will require start and end tags to be separated across multiple files
- If there is an HTML error it will be hard to track across these multiple
files
Using sed and cat
The second idea I came up with was to create some kind of template, with
separate pages and somehow include them. I thought it might be possible to
somehow use sed to do a regex replace, find
and replace something like
{ include myfile.html }
with the value of cat myfile.html. This seemed kind of tricky and too much
work.
Advantages of using sed and cat:
- Gets me that nice looking template I wanted
Disadvantages of using sed and cat:
- Requires a lot of coding and time spent trouble shooting regex, etc.
Using the C Preprocessor
I went for some help on IRC after many failed attempts to return relevant search results for my regex replacement method. After explaining my situation someone recommended the use of a preprocessor—which is exactly what I was creating without even realizing it. We found a document on the web with instructions on Using a C preprocessor as an HTML authoring tool.
In short, this allows me to create a template file:
<html>
<head>
<title>blickity blah</title>
</head>
<body>
#include "mypage.html"
</body>
</html>and run it through gcc:
gcc -E -x c -P -C sample.htm > output/sample.html
The original document goes through a breakdown of each flag, optionally you
could read the manpages for more detail (man gcc).
This was pretty neat and I could have even stopped at this but I decided to go
with a slightly more elegant solution and rather than using gcc I decided to
go with m4.
Advantages to using C Preprocessor: - The tools and language are pre-existing - It is fairly easy to invoke - No extra work needed to be done
Disadvantages to using C Preprocessor:
- Remembering the proper gcc arguments to disable the c compiler and enable it for preprocessing only is a bit cumbersome unless you are extremely familiar with gcc’s command line options.
Using M4
This method is identical to using the C Preprocessor. The difference here is that it’s a little simpler. We create a template file similar to before:
<html>
<head>
<title>blickity blah</title>
</head>
<body>
include(mypage.html)
</body>
</html>and run it through m4:
m4 index.html > output/index.html
The only issue I had here with m4 is that it was adding a newline character
after my include for some reason. To fix that I used dnl which I believe
stands for “discard new line.” If that’s too hard to remember, I like to think
of it as “do not line,” mostly because this makes no sense at all but keeps the
meaning clear. Now the original template looks something more like this:
<html>
<head>
<title>blickity blah</title>
</head>
<body>
include(mypage.html)dnl
</body>
</html>Advantages to using m4: - The tools and language are pre-existing - It is fairly easy to invoke - No extra work needed to be done
and for disadvantages… There are no real show-stopping disadvantages that I can come up with.
Wrapping it Up
Here is how I set up a small example for production work.
mkdir site
cd site/
mkdir pages templates webroot
for i in {1..5}; do echo "<p>This is page $i</p>" > pages/page-$i.html; done
Which leaves us with:
.
├── pages
│ ├── page-1.html
│ ├── page-2.html
│ ├── page-3.html
│ ├── page-4.html
│ └── page-5.html
├── templates
└── webroot
Here’s my explanation. Pages (or sections) will go into the pages/ directory.
All templates will go under templates/ the published result will be compiled
and sent to webroot/.
Now let’s create a simple template (vim templates/index.html):
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>Test Page</title>
</head>
<body>
<div id="section-1">
include(pages/page-1.html)dnl
</div>
<div id="section-2">
include(pages/page-2.html)dnl
</div>
<div id="section-3">
include(pages/page-3.html)dnl
</div>
<div id="section-4">
include(pages/page-4.html)dnl
</div>
<div id="section-5">
include(pages/page-5.html)dnl
</div>
</body>
</html>To help manage everything, I’m using a rakefile. If you don’t like rake
you’re welcome to use make or a shell script of your own. Here’s what the
Rakefile looks like (vim Rakefile):
require 'rake/clean'
SRC='templates/*.html'
DEST='webroot'
CLEAN.include("#{DEST}/*")
task :compile do
puts 'Compiling...'
templates = FileList[SRC]
templates.each do |t|
sh "m4 #{t} > #{DEST}/#{File.basename(t)}"
end
end
task :tidy do
puts 'Tidying...'
files = FileList["#{DEST}/*.html"]
files.each do |f|
sh "tidy -i -n -m #{f}"
end
end
task :default => ['compile']It’s somewhat configurable by changing the SRC and DEST variables at the
top, to allow you to name your directories differently.
Running rake will default to compiling your HTML:
rake
tree
Outputs:
.
├── Rakefile
├── pages
│ ├── page-1.html
│ ├── page-2.html
│ ├── page-3.html
│ ├── page-4.html
│ └── page-5.html
├── templates
│ └── index.html
└── webroot
└── index.html
3 directories, 8 files
and if we examine the output file:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>Test Page</title>
</head>
<body>
<div id="section-1">
<p>This is page 1</p>
</div>
<div id="section-2">
<p>This is page 2</p>
</div>
<div id="section-3">
<p>This is page 3</p>
</div>
<div id="section-4">
<p>This is page 4</p>
</div>
<div id="section-5">
<p>This is page 5</p>
</div>
</body>
</html>Success!
If you noticed, I also added a bonus tidy task which can be invoked with rake
tidy afterwards, this will allow us to format the html in a pretty way and
validate it.
blog comments powered by Disqus