Heckle: A Jekyll compatible static website builder

Heckle is a static website builder implemented in Node.js and which uses the same templating language (Liquid), site layout and configuration as Jekyll. This means that Heckle is broadly compatible with Jekyll and should be able to build any website using a Jekyll theme with a little or no modification. The main incompatibility with Jekyll relates to extensions - in Heckle, all custom tags, filters and other extensions are implemented as Node.js modules, and so are implemented in JavaScript instead of Ruby. This means that, depending on the website theme being used and its dependency on any Jekyll extenstions, that some work may be needed to port those extensions to Node.js before the website builds. However, any simple website theme that doesn't use extensions should work out of the box.

Setup

Heckle can be installed using npm:

npm install git+https://github.com/locomote-sh/heckle.git

And then run using npx:

npx heckle

Running

Similar to Jekyll, Heckle supports two run modes, build and serve.

To build a website, run:

npx heckle build <source> <target>

Where <source> is the name of the directory containing the website source, and <target> is the name of the directory where the result should be written.

To build the contents of the current directory and write the result to a folder named _site, use the -s switch instead:

npx heckle build -s

Similar to Jekyll, Heckle also provides a local HTTP service that can be used to preview and test the website during development; running the following command will build the website using the source in the current directory, and serve the result on a HTTP server listing on port 3000:

npx heckle serve -s

The server will watch for file modifications whilst running and automatically rebuild the site when changes are made.

Configuration

Site configuration can be placed within a config.yml file which uses the same general format as Jekyll's configuration file. Alternatively, if you prefer to use JSON as your configuration format then you can place that in a file named config.json and this will automatically be picked up by the build tool.

Content

HTML pages can be provided in .html files and markdown in .md files. Both sets of files can contain a frontmatter section. This is the same as in Jekyll, i.e. a YAML data section at the start of the file within --- boundary markers.

Heckle uses the same method for organization page layouts as Jekyll; so layout files should be placed in a folder named _layout/, and a page can use any available layout by specifying a layout: tag in its frontmatter section. Includes are placed in a folder named _includes/, and are then included in a page using the {% include ... %} Liquid tag.

Extensions

As mentiond above, in Heckle site extensions are implemented as a Node.js module. You specify that you want to use an extension module by providing its name in the site configuration, e.g.:

    extensions: 'exts.js'

This will load the module file named exts.js from the same folder as the site configuration.

The module can extend site functionality by exporting a number of properties. These are:

  • init: A site initialization function. Is called at the start of the site build process and is passed two arguments; the first is the build environment, and includes a property named site with the website configuration data; the second is a reference to the Liquid template engine. The init function may be an async function.
  • layouts: An object containing functional page layouts. A functional layout is a function which is used to generate a page layout programmatically.
  • tags: An object containing custom tag implementations, provided as functions which operate on the current Liquid build context.
  • filters: An object containing custom filter implementations. Filters are implemented as functions which take a value and one or more arguments, and return the result of applying the filter to its value argument. Filter functions may be async functions.