Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/foundation/panini

A super simple flat file generator.
https://github.com/foundation/panini

data flat-file gulp handlebars handlebars-helpers handlebars-partials hbs html javascript json panini partials yaml

Last synced: 30 days ago
JSON representation

A super simple flat file generator.

Awesome Lists containing this project

README 

        
# Panini



[![Build Status](https://travis-ci.org/foundation/panini.svg?branch=master)](https://travis-ci.org/foundation/panini) [![npm version](https://badge.fury.io/js/panini.svg)](https://badge.fury.io/js/panini) [![Dependency Status](https://david-dm.org/foundation/panini.svg)](https://david-dm.org/foundation/panini)



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.



## Installation



```bash

npm install panini --save-dev

```



## Usage



Feed Panini a stream of HTML files, and get a delicious flattened site out the other end.



```js

var gulp = require('gulp');

var panini = require('panini');



gulp.task('default', function() {

  gulp.src('pages/**/*.html')

    .pipe(panini({

      root: 'pages/',

      layouts: 'layouts/',

      partials: 'partials/',

      helpers: 'helpers/',

      data: 'data/'

    }))

    .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()`:



```js

gulp.watch(['./src/{layouts,partials,helpers,data}/**/*'], [panini.refresh]);

```



## Options



### `root`



**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.



### `layouts`



**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.



```html

---

layout: post

---



```



All layouts have a special Handlebars partial called `body` which contains the contents of the page.



```html



{{> body}}



```



### `pageLayouts`



**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.



```js

panini({

  root: 'src/pages/',

  layouts: 'src/layouts/',

  pageLayouts: {

    // All pages inside src/pages/blog will use the blog.html layout

    'blog': 'blog'

  }

})

```



### `partials`



**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.)



```html



{{> header}}

```



### `helpers`



**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}}`.



```js

var marked = require('marked');



module.exports = function(text) {

  return marked(text);

}

```



### `data`



**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:



```js

{

    "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.



## CLI



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 additional helpers

  --data                path to folder for additional data



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 --output=dist 'src/pages/**/*.html'

```



## Local Development



```bash

git clone https://github.com/foundation/panini

cd panini

npm install

```



Use `npm test` to run tests.