A super simple flat file generator for use with Gulp. It compiles a series of HTML pages using a common layout. These pages can also include HTML partials, external Handlebars helpers, or external data as JSON or YAML.
Panini isn't a full-fledged static site generator—rather, it solves the very specific problem of assembling flat files from common elements, using a templating language.
Note: This version of panini is not currently available via NPM, so installation must be done manually.
- git clone/download locally
- within the local directory, npm link this version
- within your project, npm link TO the local version.
See the original panini for info about NPM installation.
Feed Panini a stream of HTML files, and get a delicious flattened site out the other end.
const gulp = require('gulp');
const panini = require('panini');
gulp.task('default', function() {
return gulp
.src('pages/**/*.html')
.pipe(panini({
root: 'pages/',
layouts: 'layouts/',
partials: 'partials/',
helpers: 'helpers/',
data: 'data/',
debug: 0
}))
.pipe(gulp.dest('build'));
});Note that Panini loads layouts, partials, helpers, and data files once on first run. Whenever these files change, call panini.refresh() to get it up to date. You can easily do this inside a call to gulp.watch():
// tell panini to refresh all the files
function refreshPanini(done) {
panini.refresh();
done();
}
gulp.watch(['./src/{layouts,partials,helpers,data}/**/*'], refreshPanini);Type: String
Path to the root folder all pages live in. This option does not pull in the files themselves for processing—that's what gulp.src() is for. This setting tells Panini what the common root of your site's pages is.
Type: String
Path to a folder containing layouts. Layout files can have the extension .html, .hbs, or .handlebars. One layout must be named default. To use a layout other than the default on a specific page, override it in the Front Matter on that page.
---
layout: post
---
<!-- Uses layouts/post.html as the template -->All layouts have a special Handlebars partial called body which contains the contents of the page.
<!-- Header up here -->
{{> body}}
<!-- Footer down here -->Type: Object
A list of presets for page layouts, grouped by folder. This allows you to automatically set all pages within a certain folder to have the same layout.
The pagelayout item accepts the glob "**/*" to specify subfolders.
panini({
root: 'src/pages/',
layouts: 'src/layouts/',
pageLayouts: {
// All pages inside src/pages/blog will use the blog.html layout
'blog': 'blog',
// All pages in src/pages/article AND BELOW will use the article.html layout
'article**/*': 'article'
}
})Type: String
Path to a folder containing HTML partials. Partial files can have the extension .html, .hbs, or .handlebars. Each will be registered as a Handlebars partial which can be accessed using the name of the file. (The path to the file doesn't matter—only the name of the file itself is used.)
<!-- Renders partials/header.html -->
{{> header}}Type: String
Path to a folder containing Handlebars helpers. Handlebars helpers are .js files which export a function via module.exports. The name used to register the helper is the same as the name of the file.
For example, a file named markdown.js that exports this function would add a Handlebars helper called {{markdown}}.
var marked = require('marked');
module.exports = function(text) {
return marked(text);
}Type: String
Path to a folder containing Handlebars decorators. Handlebars decorators are .js files which export a function via module.exports. The name used to register the decorator is the same as the name of the file.
For example, a file named formatter.js that exports this function would add a Handlebars decorator called {{* formatter}}.
Type: String
Path to a folder containing external data, which will be passed in to every page. Data can be formatted as JSON (.json) or YAML (.yml). Within a template, the data is stored within a variable with the same name as the file it came from.
For example, a file named contact.json with key/value pairs such as the following:
{
"name": "John Doe",
"email": "[email protected]",
"phone": "555-1212"
}Could be used to output the value of John Doe within a template using the Handlebars syntax of {{contact.name}}.
Data can also be a .js file with a module.exports. The data returned by the export function will be used.
Data can also be inserted into the page itself with a Front Matter template at the top of the file.
Lastly, the reserved page variable is added to every page template as it renders. It contains the name of the page being rendered, without the extension.
Type: Boolean
Flag to have Panini display debugging information when rendering.
Will display the known components
- layouts
- pagelayouts
- partials
- decorators
- helpers
- data
Then, for each page rendered, the base path, page name, and layout template used to render will be displayed.
You can also use panini via the CLI.
Usage: panini --layouts=[layoutdir] --root=[rootdir] --output=[destdir] [other options] 'pagesglob'
Options:
--layouts (required) path to a folder containing layouts
--root (required) path to the root folder all pages live in
--output (required) path to the folder compiled pages should get sent to
--partials path to root folder for partials
--helpers path to folder for custom helpers (panini includes a few of its own helpers)
--decorators path to folder for decorators
--data path to folder for additional data
--debug
the argument pagesglob should be a glob describing what pages you want to apply panini to.
Example: panini --root=src/pages --layouts=src/layouts --partials=src/partials --data=src/data --debug=true --output=dist 'src/pages/**/*.html'
git clone https://github.com/zurb/panini
cd panini
npm installUse npm test to run tests.