@htmlUI

Site Templates with Static HTML and NodeJS

100% HTML

The current version of htmlUI.com is 100%, pure, static HTML (and JavaScript). No dynamic server-side, run-time HTML generating framework involved. Why? A few reasons:

  1. Performance: When all you're serving is HTML, performance and scalability are a non-issue (kind of a refreshing change of pace from dynamic runtimes)
  2. Universal Development & Hosting: In addition to doing all dev client-side, I wanted to easily develop across OSX, Windows, and anywhere else I had a few minutes to work. I also wanted the option to deploy the result to any host.
  3. No Crutch: A key reason I'm doing htmlUI.com is to explore new "HTML5" ways for doing things in the browser. By avoiding a server-side technology (for now), I'm forced to find creative development solutions to problems that server-side frameworks make easy.

True, at some point a server-side technology will be required, even if just to provide a RESTful service layer to an otherwise mostly JavaScript-driven application. But want to see how far I can go before that's required.

Of course, eliminating the "server crutch" quickly introduced some challenging problems. One challenge jumped-forward from the rest: templates.

Site Templates with Static HTML

Even before the days of server-side languages, one of the key challenges involved in maintaining websites was keeping templates in sync. Early on, there were essentially two choices:

  1. Manually update every HTML page when a change to the "template" is made (time consuming, error prone)
  2. Use software, like Dreamweaver (remember Libraries and Templates?), to do HTML partitioning and pre-compilation (clunky, proprietary template technique)

With the advent of dynamic web frameworks, like PHP or ASP, the process of compiling HTML moved to the runtime, eliminating manual precompiling steps. It solved a core problem, and it made sense at the time since more and more of a website's processing was happening on the server.

But as the world explores more of a move back to the client, putting more of a site's front-end dynamic processing in the browser, the server-side runtime dependency for basic HTML templating feels overkill. Is there a better solution for modern client-side sites?

Client-side Templates

Let's be clear upfront: moving away from a server-side tech forces us to go back to some kind of HTML pre-compilation.

Unfortunately, any kind of JavaScript/Ajaxy run-time templating has too many drawbacks to be a realistic solution. Such a dynamic approach would both penalize SEO (crawlers might not see dynamic content) and would cause a distracting load experience for users. In fact, I think the drawbacks are so widely accepted, few people have tried to go down this path (I can't find any examples on the web of people who have tried).

That means we must use something that precompiles our HTML templates. But if we're not to go back to proprietary software/techniques or server-side runtimes, what do we use?

Enter NodeJS and DocPad

As it turns-out, there is a cool solution for this problem built on NodeJS called DocPad. Built by Benjamin Loupton, this simple project provides a simple, straightforward model for "compiling" HTML at design-time. Here's how it works:

  • Define your template content in an HTML file (things like your common site header, footer, etc)
  • Use the basic templating language to indicate where HTML body content should be rendered during the DocPad compile
  • Create a content file and consume the template by including some special syntax at the top of the file

For example, let's say you have this basic template:

<html>
    <head>...</head>
    <body>
        <header>...</header>
        <div id="contentWrapper">
        <!--Render Body Content Here-->
        <%-@content%>
        </div>
        <footer>...</footer>
    </body>
</html>

Notice the <%-@content%> marker? That's DocPad's convention for indicating where content from a page using this template should render. To then consume this template (let's assume it's called "default.html"), a content page might look like this:

    - - - 
    title: "My page"
    layout: 'default'
    - - -
    <h1>My Page</h1>

When DocPad compiles the source for a site, the <h1>My Page</h1> will get rendered in to the template, and the resulting output will be a complete HTML file (let's say, MyPage.html). (As a side note, DocPad supports a few different HTML markup engines, including Markdown, Jade, and, of course, plain HTML. So we could have written the previous as #My Page#, saved the file as MyPage.md, and produced the same HTML output.)

If we need to change the template, we simply change the default.html template file, reprocess the source with DocPad, and all of our HTML pages are painlessly updated.

Benefits of NodeJS

Since DocPad is running on NodeJS, some of Node's capabilities are also exposed to the templating process. For example, you can process a list of blog posts in a folder and automatically render a list of links while a template is being processed (that's what's happening on htmlUI!). With Node's ability to access to complete file system and its growing library of plug-ins, it gives you quite of a bit of template processing power.

But if we're really being honest, more than anything it's a good excuse to get your feet wet with NodeJS, which has become very popular with the current surge in JavaScript interest.

It's like Jekyll and Hyde

There are some other popular static HTML site generators. The two that I encounter most often are Jekyll, and it's spiritual successor Hyde. Both, like DocPad, give you a way to define templates and compile static HTML, ready for distribution. Jekyll is written in Ruby. Hyde is written in Python.

Having never really used either, I can't comment fully on their power, but I can still recommend DocPad. If your goal, like mine, is to avoid "committing" to a dynamic runtime, DocPad is ideal. You don't have to "go Ruby" or "go Python." You remain 100% HTML and JavaScript, even for the dynamic template processing.

It's nothing agains Ruby or Python. It just comes back to my personal goal to see how far I can go with just JavaScript/HTML.

Final Result

Let's review:

  • The A goal for htmlUI.com is to do as much as possible without a server-side, dynamic runtime framework
  • A key problem is template maintenance.
  • DocPad is an elegant, NodeJS-based solution for dynamically generating static HTML

All of htmlUI (including this blog) is compiled with DocPad. It has solved my immediate templating problem, letting me easily maintain site templates and content without involving a dynamic runtime.

Where do I go from here? I'd like to work on a setup that would let me deploy site source from any computer to a server running DocPad, which would then automatically produce the static output and (maybe?) deploy results to my host. It is a bit of a pain to require a computer configured with Node and DocPad just to deploy a simple site update.

But it works, and the site remains 100% HTML. Hope this helps others on the journey to move front-end processing back to the browser.

-Todd

Todd Anglin

About the Author
Todd Anglin is an active speaker and author on HTML5 and web development technologies, speaking at conferences around the globe. He has a background in professional graphic design as well as professional software development. He melds his passions for design and development to currate htmlUI. During the day, Todd serves as Chief Evangelist for Telerik, an agile international software company that builds tools for software developers and development teams, including Kendo UI for HTML5 developers.

Related Posts