The last thing you want when you’re deep in a coding problem is to get slowed down by your tooling or lack thereof. Build tools like Gulp and package managers like npm give you the tools to automate tasks which saves time and reduces mistakes. When we launched Foundation 6, we open-sourced a set of build tools that we use here at ZURB code client projects called the ZURB Stack. In other words, it’s basically a way for users of Foundation to use the same tools that ZURB uses to deliver front-end code to clients. We accomplish this through the Gulp task runner and also by using a custom templating engine we wrote called, Panini. Panini is a custom built, light-weight static site generator that works as a plugin to Gulp. Together the two form a delicious-build system. This is an introductory lesson in a series on Panini. In this lesson, you’ll learn what Panini is, and how you can get started using it to optimize your workflow.

Similar to a Static Site Generator (SSG), Panini is a Node library that we developed specifically for the ZURB Stack to solve the very specific problem of compiling flat files from a bunch of elementary pieces.

Panini is a flat file compiler that uses Handlebars to compile pages from a common set of layouts, partials, and helpers.

It differs from larger static site tools like Assemble, Jekyll, or Middleman in these ways:

• A more focused feature set meant for small static sites over large content-driven sites
• More opinionated configuration, which also makes it easier to set up.

It can be used with Foundation 6 or Foundation for Emails for maintaining several templates and allows interchangeable content. Headers, footers and other repeatable content can be easily “included” in your projects and modified in one place. Handlebars gives your entire team more control and flexibility, including support for iterating over a collection (loops) and conditional data. They are also great for dynamic content.

You get the advanced build tools ZURB uses with a Foundation Sass project.

Getting A Tasty Panini

Panini can be used with the ZURB Stack or stand alone. It is implemented using JavaScript, so you’ll need a copy of node.js to get started.

You can install the ZURB Stack through the Foundation CLI (command line interface) or by downloading the ZURB Stack template and manually installing.

Instructions to install the Foundation CLI: Docs Video Tutorial

For installing manually:

You can find the Foundation 6 ZURB Stack repo here: https://github.com/zurb/foundation-zurb-template

The Foundation for Emails ZURB Stack repo is kept here: https://github.com/zurb/foundation-emails-template

Or if you want to install Panini into your existing Gulp project, you’ll find instructions here: https://github.com/zurb/panini/

Ingredients in the ZURB Stack

Once you have the ZURB Stack project created, you can open it up in your favorite code editor. You'll find this file structure:

Elements of a Good Panini Press

Panini starts processing by being given an HTML page. (In the ZURB Stack, Gulp feeds it these pages.) Pages are stored in src/pages.

A page is wrapped in a layout, which contains head and footer elements common to all pages.

A page can be further extended with these features:

Partials:

Reusable bits of HTML that can be injected into a page (or layout, or another partial).

This is a lot to take in, especially for an introductory post, but partials are a really important concept in Handlebars. A partial is essentially an include file. You can pull it into your template any time using a simple syntax:

Partials can be used in Layouts for elements used on each page (main navigation, footer), pages, or inside other partials.

Pages:

The ZURB Stack comes scaffolded to work with Panini out of the box. The pages folder contains your pages that will be injected into the {{> body}} include in the example above. This means that you do not need to copy over the head and closing body tags, JS scripts on to every page you create. Your pages are only the content on each page.

Helpers:

Custom Handlebars helpers can be written and made available in your project. Panini comes with tons of Handlebars helpers built in, like a repeat helper or markdown parser and you can add your own. For example, we wrote a previous lesson on adding a custom JS helper to Panini: /university/lessons/staying-d-r-y-with-panini

Data:

External data (formatted as JSON or YML) can be injected into Handlebars and then referenced in your project’s pages. This bridges the gap between a fully dynamic site with a database and a static site.

Works anywhere with anything

Since Panini ends up flattening all your pages and partials into your layouts, the output is regular HTML files that you can use anywhere. You’ll find the flattened pages in your dist folder along with all the other assets the ZURB Stack compiles for you.

---