biofriction-wp-theme/node_modules/panini/readme.md

169 lines
5.3 KiB
Markdown
Raw Normal View History

2021-10-26 14:18:09 +02:00
# 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.