# panini

> A super tiny flat file compiler.

Latest version **1.7.2** (published 2021-08-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install panini
pnpm add panini
yarn add panini
bun add panini
```

Provides the command `panini`.

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 1.7.2 |
| Published | 2021-08-24 |
| First published | 2015-09-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 12 |
| Unpacked size | 43.1 KB |
| Known vulnerabilities | 0 (+3 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 593 |
| Author | Foundation |
| Maintainers | gakimball, ncoden, kbal11, rafibomb, joeworkman |

## Links

- npm: https://www.npmjs.com/package/panini
- Repository: https://github.com/foundation/panini
- Homepage: https://github.com/foundation/panini#readme
- Issues: https://github.com/foundation/panini/issues
- npm.io page: https://npm.io/package/panini

## Dependencies (12)

- [glob](https://npm.io/package/glob.md) ^7.1.4
- [nopt](https://npm.io/package/nopt.md) ^4.0.1
- [slash](https://npm.io/package/slash.md) ^1.0.0
- [marked](https://npm.io/package/marked.md) ^2
- [js-yaml](https://npm.io/package/js-yaml.md) ^3.14.0
- [through2](https://npm.io/package/through2.md) ^2.0.5
- [vinyl-fs](https://npm.io/package/vinyl-fs.md) ^3.0.3
- [deepmerge](https://npm.io/package/deepmerge.md) ^1.5.2
- [strip-bom](https://npm.io/package/strip-bom.md) 2.0.0
- [handlebars](https://npm.io/package/handlebars.md) ^4.0.5
- [front-matter](https://npm.io/package/front-matter.md) ^2.0.5
- [highlight.js](https://npm.io/package/highlight.js.md) ^8.9.1

## Recent versions

- 1.7.2 (latest) — 2021-08-24
- 2.0.0-alpha.2 (next) — 2017-04-27
- 1.0.0-rc.1 (beta) — 2015-11-16
- 1.7.1 — 2020-07-23
- 1.7.0 — 2020-07-21
- 1.6.3 — 2018-10-15
- 1.6.2 — 2018-02-21
- 1.6.1 — 2018-02-11
- 1.6.0 — 2018-01-26
- 1.5.1 — 2017-07-20
- 1.5.0 — 2017-07-13
- 2.0.0-alpha.1 — 2017-04-26
- 1.4.0 — 2017-03-08
- 1.3.1 — 2016-11-03
- 1.3.0 — 2016-03-02
- … 6 more at https://npm.io/package/panini/versions

## 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
---

<!-- Uses layouts/post.html as the template -->
```

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

```html
<!-- Header up here -->
{{> body}}
<!-- Footer down here -->
```

### `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&mdash;only the name of the file itself is used.)

```html
<!-- Renders partials/header.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": "john.doe@gmail.com",
    "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.

---
_Source: https://npm.io/package/panini · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._