I have recently been building static page generators to build landing pages, including the current BatchIQ.com site.
My tool of choice so far has been Assemble. I like Assemble's integration as part of a Grunt workflow, fairly rich feature set, Handlebars templates, and flexibility of output. However, I've also had my share of thrills and spills figuring out how it does and doesn't work.
I started by using boilerplate projects such as assemble-boilerplate, grunt-init-assemble, assemble-blog-theme, and then trying to understand how and why they work. While they certainly do work and I can customize them, each seemed to approach the static site problem slightly differently, and their complexity made it hard to distill fundamental lessons about Assemble. But just accepting a complicated configuration of script, YAML, and Handlebars templates as "black magic" didn't sit well with me.
In contrast, I was inspired and informed by Andi Smith's Getting Started with Assemble articles, especially his approach of skipping the boilerplate and starting from scratch. It can be easier to learn in isolated cases. So I have decided to do the same, in perhaps more tedious detail, and share the results.
As a first step, I tried to create the most minimal "Hello, Assemble" project that I could, to get a feel for the base essence of it. I installed Grunt and Assemble, configured a single template for Assemble to process, and built out the template.
You can most easily see what this means by looking at the Gruntfile:
module.exports = function (grunt) {
grunt.initConfig({
assemble: {
hello: {
files: {
'output/': ['index.hbs']
}
}
}
});
grunt.loadNpmTasks('assemble');
};Yes, that's the entire Gruntfile. I tried cutting out the target "hello", just to be thorough in my investigation, but Assemble doesn't work without it. The most basic feature of Assemble is processing Handlebars template files from source to destination. In this case, I have only a simple file with just enough action to convince us that Assemble had processed the template.
---
title: "Hello, Assemble!"
---
<!DOCTYPE html>
<html>
<head>
<title>Learning Assemble, Step 1 - Hello, Assemble!</title>
</head>
<body>
<h1>Learning Assemble, Step 1 - Hello, Assemble!</h1>
</body>
</html>The non-html markup at the top of the file is YAML data associated with the page. In Assemble terminology, this is "front-matter". Every page has data associated with it both for the mechanics of processing (input and output file names, formats, etc.) and for content (custom data like our title).
Run grunt assemble, and it works! The output lists the templates processed:
$ grunt assemble
Running "assemble:hello" (assemble) task
Assembling output/index.html OK
>> 1 pages assembled.
Done, without errors.And the output index.html file proves that the template was really processed:
<!DOCTYPE html>
<html>
<head>
<title>Hello, Assemble!</title>
</head>
<body>
<h1>Hello, Assemble!</h1>
</body>
</html>I'm sure you are not impressed by the rich feature set, but I hope you get the point that you don't need a huge boilerplate project to get started with Assemble. It works just fine with as little as a single template and the default options.
In the next post, we'll start adding in common Assemble project options and structure towards something more practical and realistic.
For the code, please see the learning-assemble repository on GitHub. The branch step01-hello-assemble contains the code from this post.
