Lerret is a simple static site generator for image oriented sites, powered by Node.js. Whilst usable out of the box, Lerret's behaviour can be easily customised and extended through its plugin framework.
Lerret takes care of templating and image repurposing. Lerret doesn't come with any built in tools for generating stylesheets, minifying Javascript, or packaging and deploying your sites. Instead, it's recommended that you use your favourite tools directly to supplement what Lerret does well.
Lerret supports GIF, JPEG, PNG and TIFF image formats. Lerret will also extract any EXIF tags embedded in your images and make them available to your templates and plugins.
- Enhance
pug
plugin to allow any of the three templates to be optional. - Add the ability to filter which images the
convert
andcopy
plugins apply to.
- Support for Node versions 11 and earlier dropped.
- Upgraded to Pug 3. See Migrating to Pug 3 for details of how to migrate your templates.
- Refactored codebase to use async/await.
- Updated all dependencies.
- The
jade
plugin has been removed and replaced withpug
. See Migrating to Pug 2 for details of how to migrate your templates.
In order to use Lerret you need to have Node.js and npm installed. Once you have those, install Lerret as follows:
$ npm install -g lerret
Alternatively, if your site uses npm as its package manager then you may add Lerret as a dependency in your package.json file.
Once you have Lerret installed, it's simple to create a new project using the init
command.
$ mkdir my-project
$ cd my-project
$ lerret init
This creates a starting config file named lerret.yaml and directories named content, plugins and target.
$ ls
content lerret.yaml plugins target
The generate
command generates your site, but first you'll need to add some content and configure Lerret.
$ lerret generate
Lerret supports the following image formats (and corresponding file extensions) when both reading and writing images.
- GIF (
.gif
) - JPEG (
.jpeg
or.jpg
) - PNG (
.png
) - TIFF (
.tif
or.tiff
)
Lerret traverses your project's content directory building up a map of information as follows.
If the content directory contains a file named site.yaml
, then it is parsed as YAML and added to the content map at the root level.
Each directory immediately beneath the content directory is processed as an album. A list of albums is added to the content map at the root level under the key albums
.
An album is represented by a map containing a key id
with the album directory's name as its value and any other properties from the YAML file album.yaml
.
Each directory immediately beneath each album directory is processed as an image. A list of images is added to each album map under the key images
. Each image directory must contain exactly one image file, named image
and suffixed with a supported file extension.
An image is represented by a map containing a key id
with the image directory's name as its value, a key path
with the image file path as its value, a key exif
containing a map of the image's EXIF tags (if it has any), and any other properties from the YAML file image.yaml
.
The site, album and image YAML files are all optional.
The print
command outputs the content map to the console in YAML format. This is useful for validating and inspecting your site's content. Note that by default the output includes all exif tags - these may be suppressed using the --no-exif
argument.
$ lerret print
Lerret is configured in YAML. The configuration is expected in a file named lerret.yaml
in your project's root directory, the directory within which the lerret
command should be executed.
The following configuration keys are available. Plugin specific configuration is documented with each plugin below.
contentDirectory
(optional, default:./content
) - The location Lerret searches for album and image content.pluginDirectory
(optional, default:./plugins
) - The location Lerret searches for additional plugins.plugins
(required) - The list of plugins to execute. Plugins should be referred to by their name as referenced in the PLugins section below.sort
(optional)albums
(optional)property
(optional) - The property, or list of properties, of an album to sort on.order
(optional, default:asc
) - The order, or list of orders, by which to sort the albums (eitherasc
ordesc
).
images
(optional)property
(optional) - The property, or list of properties, of an image to sort on.order
(optional, default:asc
) - The order, or list of orders, by which to sort the images (eitherasc
ordesc
).
targetDirectory
(required) - The location Lerret writes the generated site to. The resulting directory structure matches that of the source content directory.
Lerret includes some core plugins which are documented below.
The convert
plugin may be used to repurpose your images. The plugin supports:
- resizing and cropping
- sharpening and quality adjustments
- conversion to different image formats
It is also possible to repurpose each image more than once with different settings.
Note: in order to use this plugin, please install GraphicsMagick.
The following configuration keys are available.
convert
(optional) - An array of conversion configurations, each containing:filename
(required) - The filename to use when writing the repurposed image to the target location.quality
(optional) - The resulting image quality (0 to 100, with 100 being best). If not specified, the GraphicsMagick default is used.resize
(optional) - Resize the image to fit the width and height values while maintaining the original aspect ratio.width
(optional) - The width in pixels. If not set, then the image is resized to the configured height and its width is set accordingly to maintain the aspect ratio.height
(optional) - The height in pixels. If not set, then the image is resized to the configured width and its height is set accordingly to maintain the aspect ratio.crop
(optional, default:false
) - Set totrue
to scale and crop the image to the configured width and height. When cropping, both width and height are required.
unsharp
(optional) - Sharpen the image with an unsharp mask operator. Please consult the GraphicsMagick documentation for an explanation of the settings below.radius
(required)sigma
(required)amount
(required)threshold
(required)
match
(optional) - Used to filter which images this conversion applies to.property
(required) - The image property to match on.regex
(required) - The regular expression applied.
The copy
plugin copies images without modification to the target location. This is useful if you have already processed your images for the web.
The following configuration keys are available.
copy
(optional)filename
(optional, default: the source image's filename) - The filename to use when copying the image to the target location.match
(optional) - Used to filter which images this plugin applies to.property
(required) - The image property to match on.regex
(required) - The regular expression applied.
The pug
plugin may be used to render Pug templates to HTML. The plugin looks for three optional templates: a home page template, an album template and an image template.
The home page template is rendered once. It is provided with a context containing the following keys.
site
- The full content map.helpers
- Additional helper module.
The album template is rendered once per album. It is provided with a context containing the following keys.
album
- The map of attributes associated with the album.site
- The full content map.helpers
- Additional helper module.
The image template is rendered once per image. It is provided with a context containing the following keys.
image
- The map of attributes associated with the image.album
- The map of attributes associated with the album which contains the image.site
- The full content map.helpers
- Additional helper module.
The following configuration keys are available. Paths are relative to the project root.
pug
(optional)helpers
(optional) - Path to a Node.js module of helper methods to pass to the template.templates
(required)home
(optional) - Path to a Pug template for the site home page.album
(optional) - Path to a Pug template for each album page.image
(optional) - Path to a Pug template for each image page.
Lerret looks for additional plugins within your project's configured pluginDirectory
. Plugins are just regular Node.js modules (files with an extension of .js
or directories containing a file named index.js
) that export an object with the following attributes.
name
(required) - The name of the plugin.processSite
(optional) - A function which is called once with the full content map.processAlbum
(optional) - A function which is called once per album.processImage
(optional) - A function which is called once per image.
Note that at least one of processSite
, processAlbum
or processImage
must be defined.
processSite
should be a function that accepts the following arguments. If the function returns a value, the content map is updated to this value and passed to subsequent plugins. If the returned value is a Promise object, it will be followed and its eventual value used.
site
- The full site content map.config
- Lerret's config module.
processAlbum
should be a function that accepts the following arguments. If the function returns a value, the album is updated to this value and passed to subsequent plugins. If the returned value is a Promise object, it will be followed and its eventual value used.
album
- The current album.index
- The index of the current album.length
- The number of albums.site
- The full site content map.config
- Lerret's config module.
processImage
should be a function that accepts the following arguments. If the function returns a value, the image is updated to this value and passed to subsequent plugins. If the returned values is a Promise object, it will be followed and its eventual value used.
image
- The current image.index
- The index of the current image.length
- The number of images.album
- The image's album.site
- The full site content map.config
- Lerret's config module.
The config module that is passed to each provides the following functions. This module allows you to access configuration data in your project's lerret.yaml
.
get(key, default)
- Returns the configuration value associated with the given key. If the key does not exist then anError
is thrown, unless a default value is provided in which case the default is returned.has(key)
- Returnstrue
if the given key exists in your config file.
To add your site here, please submit a pull request.